Liveness¶

The overview describes the common field interpretation rules, failure reasons, and full/light file formats.

Parent: liveness_result. A shared block for liveness check variants, including Head Position, Short, Distance, Distance v2, Pro Max, and Core. The set of additional scores depends on the variant and the checks actually performed.

Fields of liveness_result.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field	JSON type	Purpose and conditions
`result`	boolean	Stored technology result: `true` means accepted, `false` means a negative result. May be absent before calculation; consider the status and the details below.
`face_photo`	string	Best selected face frame; Base64 in the full response, a URL in light. When a photo is available.
`prediction`	string	Overall numeric liveness score in decimal notation, stored with 4 decimal places.
`face_direction`	string, enum	`forward` — facing forward, `right` — facing right, `left` — facing left, `not_found` — direction not found.
`face_center`	boolean	The face is in the center of the frame.
`eye_closed`	boolean	Eyes-closed indicator.
`brightness_score`	number	Lighting score.
`brightness_ok`	boolean	Whether the lighting check passed for the corresponding score.
`blurriness_score`	number	Blurriness score of the selected best frame.
`blurriness_ok`	boolean	Whether the blurriness check passed for the selected frame.
`age`	number	Estimated age of the face; may be fractional. A model estimate, not the age from a document.
`gender`	string	Gender label from the face analysis model.
`race`	string	Appearance category label from the model.
`failure_reason`	object	Failure reason, if recorded; see the structure.

This block does not return the internal Liveness processing status, video, GIF, detections, or individual model scores.

Complete examples of full and light responses with Liveness are provided in the retrieving results overview.