Docs / Face Recognition And Liveness SDK / Liveness Detection
Liveness Detection
Check that a face is a live person and not a printed photo or a screen, with passive liveness on photos and active liveness challenges in the Prod edition.
Passive Liveness (Prod And Demo)
Send one to five frames of the same person, taken within about two seconds. Five frames give the steadiest result.
curl -X POST http://localhost:8080/v2/liveness -H "x-api-key: $API_KEY" \
-F image=@f1.jpg -F image=@f2.jpg -F image=@f3.jpg -F image=@f4.jpg -F image=@f5.jpgThe answer is live, spoof or inconclusive, with the score, the threshold and the frames used. Every frame must hold exactly one face of at least 64 pixels, turned at most 25 degrees; any frame that fails makes the answer inconclusive, never live.
profile |
Use |
|---|---|
convenience (default) |
Fewer genuine users refused |
security |
Fewer attacks accepted, more genuine users asked to retry |
Passive liveness is built for printed photos and screens replayed to the camera. It is not designed to stop 3D masks.
Active Liveness (Prod)
Active liveness asks the person to follow a short random challenge, such as turning the head, and can add a colour flash from the screen. A clip prepared in advance cannot know the challenge. Start a session with POST /v2/liveness/sessions, stream the camera over its WebSocket, and read the signed result from GET /v2/liveness/sessions/{id}. Your server can check the result’s signature with the key from GET /v2/liveness/public-key.
Capture Tips
- Use the device’s real camera on a page or app you control.
- Keep the face large and evenly lit, facing the camera.
- Ask the user to retry on
inconclusive: the reasons say what to fix.
API v2. Updated 2026-11-12