API Reference

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

Shell

POST /api/v1/collections/{collection_id}/attributes
X-API-Key: <your-api-key>
Content-Type: multipart/form-data

Request

Field	Type	Description
image	file	JPEG or PNG image (max 10 MB). Must contain exactly one face.

Shell

curl -X POST \
  https://api.livexface.com/api/v1/collections/{collection_id}/attributes \
  -H "X-API-Key: YOUR_KEY" \
  -F "[email protected]"

Response

JSON

{
  "success": true,
  "data": {
    "faceDetected": true,
    "faceCount": 1,
    "primary": {
      "age": 28,
      "gender": "female",
      "detScore": 0.9821,
      "bbox": { "x": 120, "y": 45, "width": 210, "height": 240 },
      "landmarks5pt": [[185, 95], [265, 98], [225, 140], [190, 175], [260, 178]],
      "landmarks106": null,
      "headPose": {
        "yaw": 2.1, "pitch": -3.4, "roll": 0.5, "frontalScore": 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": [ "..." ],
    "imageSize": { "width": 640, "height": 480 }
  }
}

Response fields

Field	Description
faceDetected	Whether a face was found in the image.
faceCount	Number of faces detected.
primary	The highest-confidence face, repeated in full from faces[0].
faces[].age	Estimated age in years.
faces[].gender	Predicted gender ("male" or "female").
faces[].detScore	Face detection confidence (0–1).
faces[].bbox	Bounding box of the detected face in pixels.
faces[].landmarks5pt	5-point facial landmarks [[x,y], ...] (eyes, nose, mouth corners).
faces[].landmarks106	106-point facial landmarks (null if unavailable).
faces[].headPose	Head orientation: yaw, pitch, roll (degrees) and frontalScore (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.
imageSize	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.

Shell

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.45    # optional, default 0.45

JSON

{
  "success": true,
  "data": {
    "matches": [
      {
        "faceId": "dc3e7a57-22d5-4271-b707-213e49c8fe54",
        "externalId": "employee-001",
        "collectionId": "9f1c2b7e-3d84-4a16-8c55-0b7e2a1d6f30",
        "confidence": 0.94,
        "metadata": { "department": "operations" }
      }
    ],
    "queryTimeMs": 31,
    "collectionsSearched": 3
  }
}