Attributes & Search
The Face Attributes endpoint analyzes an image and returns demographic and quality attributes without requiring the face to be enrolled in any collection. It is useful for pre-screening images before enrollment or for enriching user profiles.
Endpoint
POST /api/v1/collections/{collection_id}/attributes
X-API-Key: <your-api-key>
Content-Type: multipart/form-dataRequest
| Field | Type | Description |
|---|---|---|
| image | file | JPEG or PNG image (max 10 MB). Must contain exactly one face. |
curl -X POST \
https://api.example.com/api/v1/collections/{collection_id}/attributes \
-H "X-API-Key: YOUR_KEY" \
-F "image=@photo.jpg"Response
{
"success": true,
"data": {
"face_detected": true,
"face_count": 1,
"primary": {
"age": 28,
"gender": "female",
"det_score": 0.9821,
"bbox": { "x": 120, "y": 45, "width": 210, "height": 240 },
"landmarks_5pt": [[185, 95], [265, 98], [225, 140], [190, 175], [260, 178]],
"landmarks_106": null,
"head_pose": {
"yaw": 2.1, "pitch": -3.4, "roll": 0.5, "frontal_score": 0.96
},
"emotion": {
"label": "happiness",
"confidence": 0.89,
"scores": {
"neutral": 0.08, "happiness": 0.89, "surprise": 0.01,
"sadness": 0.01, "anger": 0.0, "disgust": 0.0,
"contempt": 0.01, "fear": 0.0
}
},
"glasses": { "detected": false, "confidence": 0.12 },
"mask": { "detected": false, "confidence": 0.05 }
},
"faces": [ "..." ],
"image_size": { "width": 640, "height": 480 }
}
}Response fields
| Field | Description |
|---|---|
| face_detected | Whether a face was found in the image. |
| face_count | Number of faces detected. |
| primary | Attributes of the highest-confidence face. |
| faces[].age | Estimated age in years. |
| faces[].gender | Predicted gender ("male" or "female"). |
| faces[].det_score | Face detection confidence (0–1). |
| faces[].bbox | Bounding box of the detected face in pixels. |
| faces[].landmarks_5pt | 5-point facial landmarks [[x,y], ...] (eyes, nose, mouth corners). |
| faces[].landmarks_106 | 106-point facial landmarks (null if unavailable). |
| faces[].head_pose | Head orientation: yaw, pitch, roll (degrees) and frontal_score (0–1). |
| faces[].emotion | Dominant emotion with confidence and per-emotion scores. Labels: neutral, happiness, surprise, sadness, anger, disgust, contempt, fear. |
| faces[].glasses | Whether the subject is wearing glasses, with confidence score. |
| faces[].mask | Whether the subject is wearing a face mask, with confidence score. |
| image_size | Original image dimensions (width × height). |
Cross-Collection Search
The Search endpoint extends identification to search across all collections in your organization in a single call. Useful when you do not know which collection a person belongs to.
POST /api/v1/search
X-API-Key: <your-api-key>
Content-Type: multipart/form-data
image=@unknown_person.jpg
top_k=5 # optional, default 5
threshold=0.60 # optional, default 0.60{
"success": true,
"data": {
"found": true,
"matches": [
{
"face_id": "abc123",
"external_id": "employee-001",
"collection_id": "col-uuid",
"collection_name": "employees",
"similarity": 0.94
}
]
}
}Performance note
Cross-collection search scans every enrolled face in the organization. For large databases (100k+ faces) consider using per-collection /identify with collection routing on your side.