Liveness Detection API: Anti-Spoofing and Deepfake Checks

LumiID’s Liveness Detection API verifies that a submitted selfie belongs to a real, live person — not a photograph, screen replay, mask, or AI-generated deepfake. The check is passive: your users don’t need to blink, turn their head, or take any deliberate action. Submit a single Base64-encoded image and receive a liveness verdict and rich face-analysis metadata in under 500 ms. Use this API as the first step in any identity verification pipeline to block presentation attacks and synthetic identity fraud before they reach downstream checks.

Overview

Property	Value
Detection Type	Passive Liveness
Input	Base64 Image
Response Time	< 500 ms
Maximum Image Size	10 MB
Supported Formats	JPEG, PNG, WebP, BMP
Sandbox	Supported

Endpoint

POST /v1/ml/liveness/verify/

Headers

Header	Value
`Authorization`	`Bearer YOUR_SECRET_KEY`
`Content-Type`	`application/json`

Request body

string

required

Base64-encoded selfie image. Accepts both raw Base64 and Data URL formats (e.g. data:image/jpeg;base64,...).

Example request

{
  "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKC........."
}

Success response

{
  "data": {
    "liveness": {
      "liveness_check": true,
      "liveness_probability": 0.9971
    },
    "face": {
      "face_detected": true,
      "message": "Face detected successfully",
      "multiface_detected": false,
      "confidence": 0.9998,
      "details": {
        "age_range": { "low": 24, "high": 32 },
        "gender": { "value": "Male", "confidence": 98.4 },
        "smile": { "value": false, "confidence": 92.1 },
        "eyeglasses": { "value": false, "confidence": 99.5 },
        "sunglasses": { "value": false, "confidence": 99.8 },
        "beard": { "value": true, "confidence": 87.3 },
        "mustache": { "value": true, "confidence": 83.6 },
        "eyes_open": { "value": true, "confidence": 97.2 },
        "mouth_open": { "value": false, "confidence": 95.0 },
        "emotions": [
          { "type": "CALM", "confidence": 89.4 },
          { "type": "HAPPY", "confidence": 5.2 }
        ]
      },
      "quality": {
        "brightness": 72.4,
        "sharpness": 88.9
      },
      "bounding_box": {
        "width": 0.38,
        "height": 0.52,
        "left": 0.31,
        "top": 0.14
      }
    }
  }
}

Response fields

object

Contains the liveness result and detected-face data.

Show data.liveness

boolean

Indicates whether the selfie passed liveness. Continue your verification flow only when this is true.

float

Liveness probability score between 0.0 (definitely not live) and 1.0 (definitely live).

Show data.face

boolean

Indicates whether a face was detected in the image.

string

Human-readable face-detection result message.

boolean

Indicates whether more than one face was detected. Reject images where this is true.

float

Face-detection confidence score.

object

Estimated facial attributes and detected emotions.

Show details fields

object

Estimated age range with low and high values.

object

Estimated gender value and confidence.

object

Smile detection value (boolean) and confidence.

object

Eyeglasses detection value (boolean) and confidence.

object

Sunglasses detection value (boolean) and confidence.

object

Beard detection value (boolean) and confidence.

object

Mustache detection value (boolean) and confidence.

object

Open-eyes detection value (boolean) and confidence.

object

Open-mouth detection value (boolean) and confidence.

array

Array of emotion estimates. Each entry contains a type (e.g. CALM, HAPPY) and a confidence score.

object

Image quality measurements.

Show quality fields

float

Brightness score of the captured image.

float

Sharpness score of the captured image.

object

Relative position and dimensions of the detected face within the image, expressed as proportional values between 0 and 1.

Show bounding_box fields

float

Proportional width of the face region.

float

Proportional height of the face region.

float

Distance from the left edge of the image to the face region.

float

Distance from the top edge of the image to the face region.

Image requirements

Maximum size: 10 MB
Minimum resolution: 224 × 224 px
Accepted formats: JPEG, PNG, WebP, BMP
Encoding: Raw Base64 or Base64 Data URL
Faces per image: One — reject images with multiple faces before submitting

Error codes

HTTP	Code	Resolution
`422`	`INVALID_REQUEST`	The `image_base64` field is missing, empty, exceeds 10 MB, or is not valid Base64.
`200`	`NO_FACE_DETECTED`	No face was detected. Ask the user to retake the selfie in good lighting.
`200`	`INFERENCE_ERROR`	The analysis could not be completed. Retry the request.
`500`	`SERVER_ERROR`	Unexpected internal error. Retry once or contact LumiID Support.

Recommended verification flow

Run Liveness Detection first in your pipeline before any downstream identity check.

Capture a selfie

Capture a front-facing selfie from your user using a live camera feed.

Run Liveness Detection

Submit the selfie to this endpoint and confirm that liveness_check is true before proceeding. Reject or re-prompt if the result is false.

Verify government identity

Validate the customer’s NIN, BVN, or other government-issued identity number against the official registry.

Run Face Comparison

Compare the live selfie against the government-issued biometric photo using the Face Match API or the Government ID Face Match API.

Proceed with onboarding

Complete onboarding after all checks pass. This workflow prevents spoofing, deepfakes, synthetic identities, and impersonation fraud.

Best practices

Capture selfies in good, even lighting — avoid harsh shadows or backlit environments.
Ensure only one face is visible in the frame before submitting.
Ask users to face the camera directly without tilting or turning their head.
Reject images where the user is wearing sunglasses, a mask, or heavy filters.
Keep the face between 10% and 40% of the total image area.
Submit original camera photos rather than screenshots, image forwards, or compressed files.

Code example

Python

import requests
import base64

with open("selfie.jpg", "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("utf-8")

url = "https://api.lumiid.com/v1/ml/liveness/verify/"

payload = {
    "image_base64": image_base64
}

headers = {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

liveness = data["data"]["liveness"]

if liveness["liveness_check"]:
    print("Liveness passed. Probability:", liveness["liveness_probability"])
else:
    print("Liveness failed. Prompt the user to retake the selfie.")

Get Started

General

Government Verification

Business Verification

Biometric & AML

SDKs & Integration

Reference

Liveness Detection API: Anti-Spoofing and Deepfake Checks

Overview

Endpoint

Headers

Request body

Example request

Success response

Response fields

Image requirements

Error codes

Recommended verification flow

Best practices

Code example

​Overview

​Endpoint

​Headers

​Request body

​Example request

​Success response

​Response fields

​Image requirements

​Error codes

​Recommended verification flow

​Best practices

​Code example

Overview

Endpoint

Headers

Request body

Example request

Success response

Response fields

Image requirements

Error codes

Recommended verification flow

Best practices

Code example