Verify Face Sanity

Checks the quality of a portrait (selfie) image and returns a verdict such as good, not_qualified or occluded_face. Run it before Compare Faces or Verify Face Liveness — a poor selfie produces unreliable matching and liveness results.

Endpoint

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

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

Parameters:

Param	Type	Required	Default	Description
image	ImageData	Yes	—	The portrait image. When using the TS SDK, pass the last frontal frame.
selfie_type	string	No	—	Specifies the characteristic of a disabled face, e.g. a disabled eye, so the check adjusts accordingly.

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, never both.

Sample Request

curl -X POST \
  '<BASE_URL>/v1/verify_portrait_sanity_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

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "image": {
      "id": "4368143d-9066-4f3d-ab22-4e0b6dd9b274"
    },
    "portrait_sanity": {
      "score": 1,
      "verdict": "good"
    },
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b"
  },
  "errors": []
}

Field	Type	Description
data.status	string	success or failure.
data.image.id	string	ID of the analysed image.
data.portrait_sanity.verdict	string	good, or the first issue found. See Verdict Definitions.
data.portrait_sanity.score	float	Confidence in the verdict, range 0–1.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.

Only the first issue found is returned. Map it to a generic retake message — never show verdicts or scores to the end user.

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

• Verdict Definitions — what each face sanity verdict means
• Verify Face Liveness — confirm a live person, not a replay