Search Faces

Takes an image with a face and retrieves similar faces from a collection, each with a similarity score and its embedded metadata. This is the 1:N check for duplicate accounts and blocklist hits.

Endpoint

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

{
  "image": {
    "id": "de02a784-a7bc-43a7-96ba-226420b18960",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "collection": "default"
}

Parameters:

Param	Type	Required	Default	Description
image	ImageData	Yes	—	Image containing the face to search for.
collection	string	No	default collection	Collection to search. Case-sensitive.

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}

Sample Request

curl --location '<BASE_URL>/v1/search_faces_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "collection": "default",
    "image": {
      "id": "de02a784-a7bc-43a7-96ba-226420b18960",
      "base64": "",
      "label": "portrait",
      "metadata": "{}"
    }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "81a3cf2b-bdbb-4208-b304-3a234cf21b9c",
    "status": "success",
    "image": {
      "id": "de02a784-a7bc-43a7-96ba-226420b18960",
      "faces": [
        {
          "id": "73644de1-d727-4bce-9e8c-f5453658556a",
          "bounding_box": { "top": 154, "right": 408, "bottom": 335, "left": 173 }
        }
      ]
    },
    "faces": [
      [
        {
          "id": "452476f8-1a88-4082-a777-21250f3dbdf4",
          "image_id": "6b5b2984-a834-4c30-b6c0-c3c0720b51af",
          "score": 1
        }
      ]
    ]
  },
  "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 query image.
data.image.faces	Face[]	Faces detected in the query image, each with id and bounding_box.
data.faces	SearchMatch[][]	One array of matches per detected query face, in the same order as data.image.faces.

SearchMatch

Field	Type	Description
id	string	ID of the matched face in the collection.
image_id	string	ID of the indexed image the matched face belongs to.
score	float	Similarity between the query face and the matched face, range 0–1.

data.faces is an array of arrays — index into it by query face, then read the matches for that face.

Errors

Code	Message
2001010	Access ID not found.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
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.
request_timeout_exception	Request takes too long to process.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Index Faces — populate the collection this API searches
• Compare Faces — 1:1 comparison when you already know both images