Active Liveness Detection

Challenge-response liveness verification using head movements. Two-step process: request a challenge, then submit a video.

Step 1: Request Challenge

POST/api/v1/face_liveness_active/request

Query Parameters

Name	Default	Options
difficulty	easy	easy (1 movement), medium (2), hard (3-4)

200 OK

{
  "status": "success",
  "job_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": ["up", "left"],
  "difficulty": "medium",
  "expires_in_minutes": 10
}

Step 2: Submit Video

POST/api/v1/face_liveness_active/submit

Submit a video recording of the user performing the requested head movements.

Body (multipart/form-data)

Name	Type	Description
video	file	Video recording (mp4, webm)
job_uuid	string (query param)	Job UUID from step 1

200 OK

{
  "status": "success",
  "passed": true,
  "movement_check": {
    "passed": true,
    "detected_movements": ["up", "left"],
    "expected_movements": ["up", "left"],
    "confidence": 1.0
  },
  "liveness_check": {"passed": true, "confidence": 0.94},
  "latency_ms": 2345.67
}