> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumiid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Liveness Detection API: Anti-Spoofing and Deepfake Checks

> Detect whether a selfie is from a real, live person. Blocks spoofing, video replay, and deepfakes with LumiID's passive liveness API in under 500ms.

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

```text theme={null}
POST /v1/ml/liveness/verify/
```

### Headers

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

### Request body

**image\_base64** `string` *required*

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

#### Example request

```json theme={null}
{
  "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKC........."
}
```

### Success response

```json theme={null}
{
  "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

**data** `object`

Contains the liveness result and detected-face data.

**data.liveness**

**liveness\_check** `boolean`

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

**liveness\_probability** `float`

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

**data.face**

**face\_detected** `boolean`

Indicates whether a face was detected in the image.

**message** `string`

Human-readable face-detection result message.

**multiface\_detected** `boolean`

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

**confidence** `float`

Face-detection confidence score.

**details** `object`

Estimated facial attributes and detected emotions.

**details fields**

**age\_range** `object`

Estimated age range with `low` and `high` values.

**gender** `object`

Estimated gender `value` and `confidence`.

**smile** `object`

Smile detection `value` (boolean) and `confidence`.

**eyeglasses** `object`

Eyeglasses detection `value` (boolean) and `confidence`.

**sunglasses** `object`

Sunglasses detection `value` (boolean) and `confidence`.

**beard** `object`

Beard detection `value` (boolean) and `confidence`.

**mustache** `object`

Mustache detection `value` (boolean) and `confidence`.

**eyes\_open** `object`

Open-eyes detection `value` (boolean) and `confidence`.

**mouth\_open** `object`

Open-mouth detection `value` (boolean) and `confidence`.

**emotions** `array`

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

**quality** `object`

Image quality measurements.

**quality fields**

**brightness** `float`

Brightness score of the captured image.

**sharpness** `float`

Sharpness score of the captured image.

**bounding\_box** `object`

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

**bounding\_box fields**

**width** `float`

Proportional width of the face region.

**height** `float`

Proportional height of the face region.

**left** `float`

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

**top** `float`

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

***

## Image requirements

> [!NOTE]
>
> * **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.

**1. Capture a selfie**

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

**2. 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`.

**3. Verify government identity**

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

**4. Run Face Comparison**

Compare the live selfie against the government-issued biometric photo using the [Face Match API](https://docs.lumiid.com/api-reference/face-match) or the [Government ID Face Match API](https://docs.lumiid.com/api-reference/government-id-face-match).

**5. 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 Python theme={null}
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.")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.