Detect Faces

Detects every face in an image and optionally returns its embedding — the vector representation used for face comparison and search.

Endpoint

POST /v1/detect_faces_sync
Content-Type: application/json

{
  "image": {
    "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "return_embedding": true
}

Parameters:

Param	Type	Required	Default	Description
image	ImageData	Yes	—	Image containing the face to detect.
return_embedding	bool	No	false	Whether to return the face embedding vector.

ImageData

Param	Type	Required	Default	Description
id	string	No	—	ID of the image returned by Upload Image.
base64	string	No	—	Base64-encoded text of the image data.
label	string	No	—	Label of the image, as described in Usage Recommendations.
metadata	string_json	No	—	Key/value JSON string. Example: {"id":"<ID>","type":1}

The type key inside metadata marks the comparison context:

Field	Type	Description
1	int	Matching ID vs ID
2	int	Matching ID vs Selfie
3	int	Matching Selfie vs Selfie

Sample Request

curl -X POST \
  '<BASE_URL>/v1/detect_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": {
      "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    }
  }'

Response

{
  "data": {
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b",
    "status": "success",
    "image": {
      "id": "e5e32ef1-296e-4385-8f23-9eb7e6512800",
      "transformed_image_id": "",
      "faces": [
        {
          "id": "2cc3a440-3390-407a-914c-66a63e6eda33",
          "bounding_box": {
            "top": 402,
            "right": 257,
            "bottom": 568,
            "left": 123,
            "angle": 0
          },
          "embedding": [0.09560582041740417, -0.15577684342861176, -0.009643876925110817]
        }
      ]
    }
  },
  "errors": []
}

Field	Type	Description
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.
data.status	string	success or failure.
data.image.id	string	ID of the analysed image.
data.image.transformed_image_id	string	ID of the transformed image, present only when the image was transformed.
data.image.faces	Face[]	Faces found in the image, largest first.

Face

Field	Type	Description
id	string	ID of the face within the image.
bounding_box	BoundingBox	Position of the face in the image.
embedding	float[]	Embedding vector for the face. Returned only when return_embedding is true.

BoundingBox

Field	Type	Description
top	int	The top edge of the box.
right	int	The right edge of the box.
bottom	int	The bottom edge of the box.
left	int	The left edge of the box.
angle	int	The angle at which the box is rotated.

Faces are sorted largest first. When the input has multiple faces, use the first result.

WARNING

A face embedding is biometric data. Store it under the same controls as the source image, keep it out of logs and analytics pipelines, and delete it when the customer relationship ends.

Errors

Code	Message
2001002	Unexpected error occurred while processing the external request.
2001010	Access ID not found.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_denied_exception	You are not authorized to perform the action.
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
image_not_found_exception	The image ID is not found in DB.
request_not_found_exception	The request ID is not found when polling result by id.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Compare Faces — 1:1 matching between two images
• Index Faces — enrol a detected face into a collection