Compare Faces

Compares the faces in two images and returns whether they belong to the same person — matched, unmatched or unsure — with a similarity score from 0 to 1. This is the 1:1 check that ties a selfie to an ID card portrait.

Endpoint

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

{
  "image1": {
    "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "image2": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  },
  "type": ""
}

Parameters:

Param	Type	Required	Default	Description
image1	ImageData	Yes	—	The first image containing a face to compare with image2.
image2	ImageData	Yes	—	The second image containing a face to compare with image1.
type	string	No	default	Specifies the type of face comparison for special cases. Omit to use the default.

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}

Supply either id or base64 per image, never both.

Sample Request

curl -X POST \
  '<BASE_URL>/v1/compare_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image1": { "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74" },
    "image2": { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "compare_faces": [
      {
        "face1_id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4",
        "face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
        "result": "matched",
        "score": 0.95
      },
      {
        "face1_id": "ae7a6cd2-4f5b-45b3-955f-844b1bc6d95a",
        "face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
        "result": "unmatched",
        "score": 0.1
      }
    ],
    "image1": {
      "id": "f3f6f8b5-2ac0-4734-a4b5-836c6c300b0b",
      "transformed_image_id": "",
      "faces": [
        {
          "id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4",
          "bounding_box": { "top": 172, "right": 550, "bottom": 446, "left": 357, "angle": 0 }
        }
      ]
    },
    "image2": {
      "id": "639058a6-0631-4bfd-a718-bc72c2695daf",
      "transformed_image_id": "",
      "faces": [
        {
          "id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
          "bounding_box": { "top": 296, "right": 559, "bottom": 369, "left": 504, "angle": 0 }
        }
      ]
    },
    "request_id": "b6e90aa2-a2d2-44bb-b4d5-cd4b92d0cdae"
  },
  "errors": []
}

Field	Type	Description
data.status	string	success or failure.
data.compare_faces	ComparePair[]	Every face pair evaluated, largest pair first.
data.image1	ImageResult	Faces detected in the first image.
data.image2	ImageResult	Faces detected in the second image.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.

ComparePair

Field	Type	Description
face1_id	string	ID of the face in image1.
face2_id	string	ID of the face in image2.
score	float	How likely the two faces are the same person, range 0–1. 0 means no similarity at all.
result	string	matched, unmatched or unsure. See Verdict Definitions.

ImageResult

Field	Type	Description
id	string	ID of the image.
transformed_image_id	string	ID of the transformed image, present only when the image was transformed.
faces	Face[]	Faces detected in the image, each with id and bounding_box (top, right, bottom, left, angle).

The largest pair of faces is sorted first. When the selfie contains multiple faces, use the first pair in compare_faces.

INFO

unsure is a real outcome, not a soft matched. Route unsure results to manual review rather than folding them into either branch of an automated decision.

Errors

Code	Message
2001003	Image sent to the server has no faces.
2001010	Access ID not found.
2001026	Images sent to server are duplicated.
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.
4041000	The image ID is not found in DB.
4131000	The input image size exceeds the allowed limit (15MB).
4151000	The provided image format is not supported (JPG/PNG).
4291000	The number of requests exceeded your throughput limit.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_id_not_found	Access ID not found.
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.
image_too_large_exception	The input image size exceeds the allowed limit (15MB).
invalid_image_format_exception	The provided image format is not supported (JPG/PNG).
duplicated_image	Images sent to server are duplicated.
image_has_no_faces	Image sent to the server has no faces.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Search Faces — 1:N search across a collection instead of a single pair
• Verdict Definitions — the meaning of matched, unmatched and unsure