UbixFace API Documentation

Welcome to the UbixFace API. This API allows authorized users (Gold subscribers) to perform face recognition through a simple RESTful interface. The API returns recognized face names from uploaded photos, with options for saving results and usage tracking.

🔐 Authentication

Only Gold Plan users are granted API access.

🔗 Endpoint

POST https://ubix.pics/api/analyze

Headers

Authorization: Bearer <api_token>

Body Parameters

Field	Type	Required	Description
photo	File	Yes	Image file (jpg, jpeg, png)
save	Boolean	No	Save result as annotated image
tolerance	Float	No	Face match sensitivity (0.2–0.6). Default: 0.45

Tolerance Explained

The tolerance parameter defines how strict the face comparison algorithm should be:

0.2–0.3: Strict – for high-accuracy security scenarios.
0.35–0.45: Recommended – best balance for consumer apps.
0.5–0.6: Lenient – more likely to allow lookalikes.

📌 Adjust tolerance based on image quality, lighting, and use case.

Validation Rules

If not provided, default is 0.45
Must be between 0.2 and 0.6
Returns error JSON if out of range or invalid

{ "error": "Tolerance must be between 0.2 and 0.6" }

{ "error": "Invalid tolerance value" }

📊 Rate Limiting

Limit: 60 requests per minute per API token.
Exceeding the limit returns HTTP 429 Too Many Requests.

📟 Responses

✅ 200 OK

{
  "names": ["Alice", "Bob"],
  "quota_remaining": 8,
  "quota_used_percent": 20
}

⚠️ No Faces

{
  "names": [],
  "message": "No faces detected."
}

❌ Error Samples

HTTP Code	Message	Cause

401	Invalid API token	Missing or incorrect token
429	Analysis limit exceeded	Quota used up
400	Invalid image format	Unsupported image type
400	Tolerance must be between 0.2 and 0.6	Invalid tolerance
400	Invalid tolerance value	Could not convert to float
413	Image file too large	> 18MB
500	Failed to process image	Internal server error

💡 Example Usage

Curl

curl -X POST https://yourdomain.com/api/analyze \
  -H "Authorization: Bearer <api_token>" \
  -F "[email protected]" \
  -F "save=true" \
  -F "tolerance=0.4"

Python (requests)

import requests

with open("face.jpg", "rb") as f:
    res = requests.post(
        "https://yourdomain.com/api/analyze",
        headers={"Authorization": f"Bearer {token}"},
        files={"photo": f},
        data={"save": "true", "tolerance": "0.4"}
    )

print(res.json())

📤 Upload New Face

This endpoint lets Gold-tier users upload and register a new face for later recognition via the API or web dashboard.

🔗 Endpoint

POST https://ubix.pics/api/upload_face

Headers

Authorization: Bearer <api_token>

Body Parameters

Field	Type	Required	Description
photo	File	Yes	Image of the person (jpg, jpeg, png)
person_name	String	Yes	Name to associate with this face

📊 Rate & Usage Limits

60 requests per minute per API token
Image size limit: 18MB
Face count limit: based on subscription plan

✅ Success Response

{
  "status": "success",
  "message": "Face uploaded successfully.",
  "face_name": "John Doe"
}

❌ Error Responses

HTTP	Message	Cause
401	Invalid API token	Missing or invalid token
400	Person name is required.	Missing form field
400	Invalid image format	File not jpg/png/jpeg
429	Faces limit exceeded	Exceeded face quota
413	Image file too large	Over 18MB
200	No faces detected.	No face found in image

💡 Example Usage

Curl

    curl -X POST https://ubix.pics/api/upload_face \
      -H "Authorization: Bearer " \
      -F "[email protected]" \
      -F "person_name=John Doe"

Python (requests)

  import requests

  with open("john.jpg", "rb") as f:
      res = requests.post(
          "https://ubix.pics/api/upload_face",
          headers={"Authorization": f"Bearer {token}"},
          files={"photo": f},
          data={"person_name": "John Doe"}
      )
  print(res.json())

🛡️ Security Notes

Tokens are not stored in the DB, only generated at runtime.
Token renew automatically every 72 Hours.

Contact Us

To learn more about Ubix.pics, explore partnerships, please reach out to us at [email protected]