> For the complete documentation index, see [llms.txt](https://docs.lumiid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumiid.com/api-integration/biometric-checks/liveness-detection-api-or-selfie-anti-spoofing-and-deepfake-checks.md).

# Liveness Detection API | Selfie Anti-Spoofing and Deepfake Checks

Verify that a selfie belongs to a **real, live person** with LumiID's AI-powered passive liveness detection API. Use a single Base64-encoded image for biometric verification, KYC onboarding, and authentication.

The API returns a **LIVE**, **SPOOF**, or **INCONCLUSIVE** verdict. It evaluates facial geometry, skin texture, image quality, metadata, and deepfake fingerprints to prevent identity fraud.

Designed for fintechs, banks, identity platforms, healthcare, government services, and enterprise KYC workflows.

***

## Overview

|                        |                         |
| ---------------------- | ----------------------- |
| **Authentication**     | API Key Required        |
| **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**

```http
{{baseUrl}}/v1/liveness/check/
```

***

## Headers

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

***

## Request Body

| Field   | Type   | Required | Description                                                                                               |
| ------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `image` | string | ✅        | Base64-encoded selfie image. Accepts both raw Base64 and Data URL formats (`data:image/jpeg;base64,...`). |

#### Example Request

```json
{
    "image":"BASE64_ENCODED_IMAGE"
}
```

***

## Successful Response

```json
{
  "status": "success",
  "request_id": "lv_ed03dff154544010",
  "timestamp": "2026-03-19T07:12:51.430216Z",
  "result": {
    "verdict": "LIVE",
    "confidence": 0.7916,
    "threshold": 0.58,
    "face_detected": true,
    "signals": [
      {
        "name": "sharpness",
        "label": "Image sharpness",
        "score": 0.3622,
        "weight": 0.12,
        "passed": false,
        "detail": "Image appears soft or blurry."
      },
      {
        "name": "lbp_texture",
        "label": "LBP skin texture",
        "score": 0.8558,
        "weight": 0.20,
        "passed": true,
        "detail": "Skin texture matches a real face captured by a camera."
      }
    ]
  },
  "error": null
}
```

***

## Response Fields

### Top-Level Response

| Field        | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `status`     | string | `success` or `error`. Always check this field first. |
| `request_id` | string | Unique request identifier for auditing and support.  |
| `timestamp`  | string | UTC response timestamp in ISO 8601 format.           |
| `result`     | object | Liveness analysis result. Present on success.        |
| `error`      | object | Error details. Present on failure.                   |

***

### `result`

| Field           | Type    | Description                                                   |
| --------------- | ------- | ------------------------------------------------------------- |
| `verdict`       | string  | `LIVE`, `SPOOF`, or `INCONCLUSIVE`.                           |
| `confidence`    | float   | Overall confidence score between **0.0** and **1.0**.         |
| `threshold`     | float   | Decision threshold used by the engine.                        |
| `face_detected` | boolean | Indicates whether a face was detected in the submitted image. |
| `signals`       | array   | Detailed anti-spoofing signal results.                        |

***

### `signals`

Each signal explains how a particular anti-spoofing check contributed to the final decision.

| Field    | Type    | Description                                      |
| -------- | ------- | ------------------------------------------------ |
| `name`   | string  | Internal signal identifier.                      |
| `label`  | string  | Human-readable signal name.                      |
| `score`  | float   | Signal confidence score.                         |
| `weight` | float   | Contribution to the final confidence score.      |
| `passed` | boolean | Indicates whether the signal passed.             |
| `detail` | string  | Plain-language explanation of the signal result. |

***

## Verdicts

#### LIVE

The submitted selfie matches the characteristics of a genuine live person.

**Recommended Action**

Continue the identity verification or onboarding process.

***

#### SPOOF

The selfie shows characteristics commonly associated with presentation attacks such as:

* Printed photographs
* Mobile screen replays
* Photo-of-a-photo attacks
* AI-generated faces
* Face swap images

**Recommended Action**

Reject the verification attempt or request additional verification.

***

#### INCONCLUSIVE

The engine could not confidently determine whether the subject is live.

This typically occurs because of:

* Poor lighting
* Blurry images
* Heavy face occlusion
* Extreme head angles
* No face detected

**Recommended Action**

Ask the user to retake the selfie.

***

## Confidence Score Guide

| Score           | Interpretation            |
| --------------- | ------------------------- |
| **0.80 – 1.00** | Strong LIVE               |
| **0.62 – 0.79** | Moderate LIVE             |
| **0.54 – 0.61** | Borderline (INCONCLUSIVE) |
| **0.35 – 0.53** | Likely SPOOF              |
| **0.00 – 0.34** | Strong SPOOF              |

***

## Detection Signals

LumiID combines multiple AI signals into a single fraud decision.

| Signal                   | Purpose                                                             |
| ------------------------ | ------------------------------------------------------------------- |
| Image Sharpness          | Detects blurry or recaptured images.                                |
| Eye Aspect Ratio         | Confirms naturally open human eyes.                                 |
| Head Pose                | Detects unnatural head orientation.                                 |
| Face Area Ratio          | Validates proper selfie framing.                                    |
| Facial Symmetry          | Measures facial alignment and distortion.                           |
| LBP Skin Texture         | Detects real skin micro-texture versus printed or digital displays. |
| EXIF Metadata            | Evaluates camera metadata where available.                          |
| FFT Deepfake Fingerprint | Detects AI-generated faces and deepfake artifacts.                  |

No single signal determines the final verdict. LumiID combines all signals to produce a weighted confidence score.

***

## Image Requirements

| Requirement        | Value                |
| ------------------ | -------------------- |
| Maximum Size       | 10 MB                |
| Minimum Resolution | 224 × 224 px         |
| Accepted Formats   | JPEG, PNG, WebP, BMP |
| Encoding           | Base64 or Data URL   |
| Faces per Image    | One                  |

***

## Best Practices

For the highest detection accuracy:

* Capture the selfie in good lighting.
* Ensure only one face is visible.
* Face the camera directly.
* Avoid sunglasses, masks, and heavy filters.
* Keep the face between **10% and 40%** of the image.
* Submit original camera photos rather than screenshots or compressed forwards.

***

## Error Codes

| HTTP    | Code               | Resolution                                                                             |
| ------- | ------------------ | -------------------------------------------------------------------------------------- |
| **422** | `INVALID_REQUEST`  | The `image` 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.                               |
| **200** | `INFERENCE_ERROR`  | The analysis could not be completed. Retry the request.                                |
| **500** | `SERVER_ERROR`     | Unexpected internal error. Retry once or contact LumiID Support with the `request_id`. |

***

## Security & Compliance

* All requests must use **HTTPS**.
* Images are processed securely over encrypted connections.
* Every request returns a unique `request_id` for auditing and troubleshooting.
* Handle biometric data in accordance with **NDPR**, GDPR, and your organization's privacy policies.

***

## Common Use Cases

The Liveness Detection API is commonly used for:

* Digital onboarding
* Identity verification (KYC)
* Banking and fintech
* Account recovery
* Passwordless authentication
* Employee verification
* SIM registration
* Fraud prevention
* Government digital identity services

***

## Recommended Identity Verification Flow

For maximum fraud protection, LumiID recommends the following verification pipeline:

1. Capture a user selfie.
2. Run the **Liveness Detection API** to confirm a real, live person.
3. Verify the user's government-issued identity (NIN, BVN, Passport, etc.).
4. Compare the live selfie against the government-issued photo using the **Face Comparison API**.
5. Continue onboarding after successful verification.

This workflow helps prevent spoofing, presentation attacks, deepfakes, synthetic identities, and impersonation fraud.

***

### Liveness detection FAQ

#### What is passive liveness detection?

Passive liveness detection analyzes a selfie without requiring user actions. Users do not need to blink, turn, or speak.

#### Which liveness verdicts can the API return?

The API returns `LIVE`, `SPOOF`, or `INCONCLUSIVE`. Use the verdict with its confidence score in your decision flow.

#### What image format does the API accept?

Submit one selfie as raw Base64 or a Base64 Data URL. JPEG, PNG, WebP, and BMP are supported.

#### Does liveness detection replace identity verification?

No. Pair it with government ID verification and face comparison for higher assurance.

***

## Example (Python)

```python
import requests
import base64

with open("selfie.jpg", "rb") as image:
    encoded = base64.b64encode(image.read()).decode()

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

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

payload = {
    "image": encoded
}

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

data = response.json()

if data["status"] == "success":
    print("Verdict:", data["result"]["verdict"])
    print("Confidence:", data["result"]["confidence"])
    print("Request ID:", data["request_id"])
else:
    print(data["error"]["message"])
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lumiid.com/api-integration/biometric-checks/liveness-detection-api-or-selfie-anti-spoofing-and-deepfake-checks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.