Verify Face Liveness

Determines whether a portrait image shows a live person in front of the camera rather than a printed photo, a screen replay or another presentation attack.

Endpoint

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

{
  "images": [
    {
      "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
      "base64": "",
      "label": "portrait",
      "metadata": "{}"
    }
  ]
}

Parameters:

Param	Type	Required	Default	Description
images	ImageData[]	Yes	—	One or more portrait images captured during the liveness step.

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/verify_face_liveness_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "images": [
      {
        "id": "ba056dc8-e702-4292-90b5-5c549c4db956",
        "base64": "",
        "label": "portrait",
        "metadata": "{}"
      }
    ]
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "88b35583-76e0-4380-8a0b-a2d86436b6a5",
    "status": "success",
    "is_live": true,
    "score": 1,
    "images": [
      {
        "id": "ba056dc8-e702-4292-90b5-5c549c4db956",
        "is_live": true,
        "score": 0.9998822
      }
    ],
    "main_image_id": ""
  },
  "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.is_live	bool	Overall liveness result across all submitted images.
data.score	float	Overall liveness confidence, range 0–1.
data.images	LivenessResult[]	Per-image liveness result.
data.main_image_id	string	ID of the image the overall verdict was drawn from, when one was selected.

LivenessResult

Field	Type	Description
id	string	ID of the image.
is_live	bool	Whether this image shows a live person.
score	float	Liveness confidence for this image, range 0–1.

WARNING

Evaluate liveness on the server from the API response, never from a client-reported result. A compromised mobile client can claim is_live: true; only your backend reading a signature-verified response can be trusted.

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.
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 — match the live selfie against the ID card portrait
• Verdict Definitions — the is_live and incorrect_image_type verdicts in context