UBIX.PICS

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
photoFileYesImage file (jpg, jpeg, png)
saveBooleanNoSave result as annotated image
toleranceFloatNoFace match sensitivity (0.2–0.6). Default: 0.45

Tolerance Explained

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

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

Validation Rules

{ "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
401Invalid API tokenMissing or incorrect token
429Analysis limit exceededQuota used up
400Invalid image formatUnsupported image type
400Tolerance must be between 0.2 and 0.6Invalid tolerance
400Invalid tolerance valueCould not convert to float
413Image file too large> 18MB
500Failed to process imageInternal 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
photoFileYesImage of the person (jpg, jpeg, png)
person_nameStringYesName to associate with this face

📊 Rate & Usage Limits

✅ Success Response

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

❌ Error Responses

HTTP Message Cause
401Invalid API tokenMissing or invalid token
400Person name is required.Missing form field
400Invalid image formatFile not jpg/png/jpeg
429Faces limit exceededExceeded face quota
413Image file too largeOver 18MB
200No 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

Contact Us