BrandKwikID Documentation
API SuiteFace & Biometrics (ML)

Liveness Detection

Analyze image and optional video for presentation attack detection. Server-side multipart POST with Bearer auth.

API reference

Try itLoading playground…
Loading…

Authorization

AuthorizationBearer <token>

JWT Bearer token authentication. Obtain a token from the KwikID dashboard.

In: header

Request Body

imagestring
video?string
enhanced_detection?string

Optional. When image and video are both present: True (default) uses multi-frame analysis; False uses legacy image+blink path.

facematch_frames?string

Optional. When image+video: number of video frames to compare to the still (default 3).

facematch_threshold?string

Optional. When image+video: fraction of frames that must match for a positive facematch (default 0.6).

frame_sampling_rate?string

Optional. When enhanced (image+video): sample every Nth frame (default 15).

max_frames_to_analyze?string

Optional. When enhanced: cap on frames analyzed (default 20).

image_type?string

Optional. Use file when uploading a file (default). Other values apply only when your integration sends non-file image payloads.

unique_id?string

Optional. Correlation id for logs.

image?string
videostring
enhanced_detection?string

Optional. When image and video are both present: True (default) uses multi-frame analysis; False uses legacy image+blink path.

facematch_frames?string

Optional. When image+video: number of video frames to compare to the still (default 3).

facematch_threshold?string

Optional. When image+video: fraction of frames that must match for a positive facematch (default 0.6).

frame_sampling_rate?string

Optional. When enhanced (image+video): sample every Nth frame (default 15).

max_frames_to_analyze?string

Optional. When enhanced: cap on frames analyzed (default 20).

image_type?string

Optional. Use file when uploading a file (default). Other values apply only when your integration sends non-file image payloads.

unique_id?string

Optional. Correlation id for logs.

imagestring
videostring
enhanced_detection?string

Optional. When image and video are both present: True (default) uses multi-frame analysis; False uses legacy image+blink path.

facematch_frames?string

Optional. When image+video: number of video frames to compare to the still (default 3).

facematch_threshold?string

Optional. When image+video: fraction of frames that must match for a positive facematch (default 0.6).

frame_sampling_rate?string

Optional. When enhanced (image+video): sample every Nth frame (default 15).

max_frames_to_analyze?string

Optional. When enhanced: cap on frames analyzed (default 20).

image_type?string

Optional. Use file when uploading a file (default). Other values apply only when your integration sends non-file image payloads.

unique_id?string

Optional. Correlation id for logs.

Response Body

curl -X POST "https://__mock__/liveness"
{
  "result": "real",
  "confidence": 1,
  "blink_detection": true,
  "image_input": true,
  "video_input": true,
  "facematch_result": "True",
  "facematch_confidence": 1,
  "facematch_frames_tested": 0,
  "overall_result": "True",
  "overall_confidence": 1,
  "image_result": "real",
  "image_confidence": 1,
  "video_frames_analyzed": 0,
  "real_video_frames": 0,
  "total_video_frames": 0,
  "enhanced_detection": true,
  "frame_sampling_rate": 0,
  "max_frames_analyzed": 0
}
{
  "detail": {
    "<location>": {
      "<field_name>": [
        "string"
      ]
    }
  },
  "message": "string"
}
{
  "detail": {},
  "message": "string"
}

Overview

Call POST /liveness with Authorization: Bearer <token> and multipart/form-data. Supported combinations: still + MP4 video (full pipeline with optional facematch across frames), still only, or video only. The published OpenAPI schema (LivenessMultipartRequest) uses oneOf so primary inputs (image, video, or both) are grouped separately from optional tuning strings (enhanced_detection, frame_sampling_rate, max_frames_to_analyze, facematch_frames, facematch_threshold, image_type, unique_id).

Key features

  • Spoof resistance: Adds signal beyond static face match.
  • Pairs with Facematch: Run liveness before or after Facematch per your risk policy.

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:

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

Implementation

Step 1: Call from your backend

Send image and/or video per the mode you need; see OpenAPI for optional tuning fields.

Error handling

HTTP statusWhen
400Missing required media or bad format.
401Invalid token.

Benefits

  • Supports RBI-aligned video KYC journeys when combined with your orchestration.

Next steps

Delete Faces from Collection POST

Remove a face from the AWS Rekognition collection by bucket and external_image_id. POST /delete_faces_from_collection with Bearer auth.

Liveness Detection V2 POST

Same liveness flows as v1 with a structured multi-block JSON response (image, video, facematch, overall). POST /v2/liveness with Bearer auth.