Liveness Detection

Liveness Detection verifies whether a face belongs to a real, live person by analyzing frame data, phases, and user challenge responses.

Response Schema

Liveness Detection Response — LivenessDetectionResult

The liveness detection workflow runs over a WebSocket connection and returns multiple message types during the verification process.

Phase Transition Message

type

• Type: string
• Value: "phase" Indicates a phase transition during the liveness workflow.

value

• Type: string
• Enum: "passive" | "active"
• passive → anti-spoofing evaluation
• active → challenge-based verification

Frame Result Message

type

• Type: string
• Value: "frame_result" Indicates that the current video frame has been analyzed.

confidence

• Type: number
• Range: [0.0, 1.0] Confidence score from anti-spoofing models for this frame.

label

• Type: string
• Enum: "REAL" | "FAKE" Classification of the frame.

Challenge Start Message

type

• Type: string
• Value: "challenge_start"

action

• Type: string
• Enum: "BLINK" | "LOOK LEFT" | "LOOK RIGHT" | "LOOK UP" | "LOOK DOWN" | "SMILE"

Challenge Result Message

type

• Type: string
• Value: "challenge_result"

action

• Type: string

status

• Type: string
• Enum: "passed" | "failed"

Final Result Message

type

• Type: string
• Value: "final_result"

label

• Type: string
• Enum: "REAL" | "FAKE"

passed

• Type: Array<string>

confidence

• Type: number
• Range: [0.0, 1.0]
• Optional

Example Responses

Phase Transition Example

{
  "type": "phase",
  "value": "passive"
}

Frame Result Example

{
  "type": "frame_result",
  "confidence": 0.874,
  "label": "REAL"
}

Challenge Start Example

{
  "type": "challenge_start",
  "action": "BLINK"
}

Challenge Result Example

{
  "type": "challenge_result",
  "action": "BLINK",
  "status": "passed"
}

Final Result Example — Live Person

{
  "type": "final_result",
  "label": "REAL",
  "passed": ["BLINK", "LOOK_RIGHT"],
  "confidence": 0.91
}

Final Result Example — Spoof Detection

{
  "type": "final_result",
  "label": "FAKE",
  "passed": [],
  "confidence": 0.34
}