This endpoint is a passive, single-image heuristic pass, not certified presentation-attack detection (PAD). It combines detector confidence, image sharpness, and face-crop size into a weak signal that catches the crudest attacks (a printed photo, a low-quality screen replay) and nothing more. See Models → Liveness heuristic for exactly what it does and doesn’t protect against before relying on it for a production go-live decision.
Runs face detection on a single frame, then evaluates three independent heuristics against configurable floors. All three must pass for the overall result to be passed: true.

​
Request

​
file
required
A single frame, as multipart/form-data. Same decode/size constraints as /v1/embed’s image field.

​
Response

​
boolean
true only if detector confidence, face-crop sharpness, and face size all clear their respective floors (see Configuration → Liveness for the env vars).
​
float
A [0, 1] blended score for observability — not itself the pass/fail decision (that’s the per-check floors above). Useful for tuning floors against real traffic before locking them down.
​
string | null
null when passed is true. Otherwise one of low_detector_confidence, face_too_small, or low_sharpness_score — whichever heuristic failed first.

​
Errors

Same shape as /v1/embed — no_face_detected / undecodable_image on 422, missing_field_image on 400.
This endpoint does not call the embedder model at all — only the detector, plus OpenCV sharpness math on the resulting face crop. It’s cheap by design; the plan is for callers to run this before (or alongside) /v1/embed//v1/compare, not as a heavyweight extra pass.