Liveness Detection V2

API reference

curl -X POST "https://__mock__/v2/liveness"

{
  "image": {
    "input_provided": "True",
    "result": "real",
    "confidence": 95,
    "prediction_confidence": 95
  },
  "video": {
    "input_provided": "True",
    "result": "real",
    "confidence": 90.45,
    "prediction_confidence": 90.45,
    "blink_detection": "True",
    "video_frames_analyzed": 20,
    "real_video_frames": 18,
    "total_video_frames": 300,
    "enhanced_detection": "True",
    "frame_sampling_rate": 15,
    "max_frames_analyzed": 20
  },
  "image_video_facematch": {
    "performed": "True",
    "result": "True",
    "confidence": 88.5,
    "frames_tested": 3
  },
  "overall_result": "True",
  "overall_confidence": 92.94
}

{
  "detail": {
    "<location>": {
      "<field_name>": [
        "string"
      ]
    }
  },
  "message": "string",
  "msg": "string"
}

{
  "detail": {},
  "message": "string"
}

Overview

Call POST /v2/liveness with Authorization: Bearer <token> and multipart/form-data. Input modes match Liveness Detection (v1): still + MP4 video (enhanced multi-frame path with face match across frames), still only, or video only. Published OpenAPI (LivenessMultipartRequest) uses oneOf so primary inputs (image, video, or both) are separate from optional tuning strings (frame_sampling_rate, max_frames_to_analyze, facematch_frames, facematch_threshold, enhanced_detection, image_type, unique_id). Tuning behavior matches v1.

Flow at a glance

Illustrative only: shows how requests move through outcomes, without describing internal models or proprietary logic.

What changes in V2: the 200 body is no longer a single flat object. It returns:

• image: whether an image was supplied, liveness result, confidence, and optional prediction_confidence (see below).
• video: same pattern for the video path, plus frame counts, blink, and enhanced-mode metadata when applicable.
• image_video_facematch: whether facematch ran, result, confidence (percentage 0 to 100 when performed), frames_tested.
• overall_result and overall_confidence: combined decision; confidence is 0 when the overall outcome is a failure (for example False or fake).

confidence vs prediction_confidence

For image and video blocks, when the modality is classified as fake, confidence is returned as 0 and the score before that rule is available in prediction_confidence when the service has a numeric score. This keeps a clear failed/passed signal while preserving the underlying score for auditing or UI.

200 response: keys, definitions, examples

Top-level keys are objects image, video, image_video_facematch, plus scalars overall_result and overall_confidence. Examples below are typical for a successful image + video run; strings like "True" / "False" are returned as strings, not JSON booleans. Fields often become null or "N/A" when that part of the pipeline did not run.

Key features

• Structured responses: Easier to store, display, or policy-check each part of the check without parsing a flat mix of fields.
• Same integration surface as v1 for multipart inputs and tuning parameters.
• Pairs with Facematch: Conceptually aligned with Facematch; V2 embeds still-vs-video facematch in the image_video_facematch block when you send both image and video.

Bulk testing in the Playground

The Playground on this page supports Bulk (ZIP batch) mode. Screenshots, naming rules, Run, completion download, and output archive layout are documented on Facematch:

• How to use bulk testing in the Playground

Switch this page’s Playground to Bulk and follow the same flow; shape your ZIP inputs to match POST /v2/liveness (see OpenAPI on this page).

Implementation

Step 1: Call from your backend

Send image and/or video as for v1. Point your client at the v2 route on your ML base URL (for deployments that expose SUMI under an app prefix, this is commonly .../sumi/v2/liveness).

Error handling

Benefits

• Clear separation of image liveness, video liveness, and optional facematch in one response.

Related

• Liveness Detection (v1)
• Facematch
• API Suite index