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" The user challenge that must be performed.

Challenge Result Message

type

• Type: string
• Value: "challenge_result"

action

• Type: string The challenge action being evaluated.

status

• Type: string
• Enum: "passed" | "failed" Outcome of the performed challenge.

Final Result Message

type

• Type: string
• Value: "final_result"

label

• Type: string
• Enum: "REAL" | "FAKE" Final decision on whether the user is live or spoofing.

passed

• Type: Array<string> List of successfully completed challenges.

confidence

• Type: number
• Range: [0.0, 1.0]
• Optional Overall confidence score for the final liveness result.

Example Responses

Listing : Phase Transition Example

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

Listing : Frame Result Example

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

Listing : Challenge Start Example

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

Listing : Challenge Result Example

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

Listing : Final Result Example - Live Person

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

Listing : Final Result Example - Spoof Detection

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