# Liveness Detection API

# Overview

The Liveness Detection API provides AI-powered face liveness detection to distinguish between real, live faces and spoofing attempts (photos, videos, masks, or deepfakes). This API is essential for secure identity verification, preventing fraud, and ensuring that the person being verified is physically present.

Key Features:

Spoof Detection: Identify presentation attacks (photos, videos, masks)
Real-time Analysis: Fast liveness verification for seamless user experience
High Accuracy: Advanced AI models trained on diverse spoofing scenarios
Passive Detection: No user interaction required (no blinking or head movement challenges)
Regional Deployment: Available in multiple regions for low latency

# Base URLs

Region	Base URL
EU	`https://liveness-detection-api-eu.realeyes.ai/v1/`
US	`https://liveness-detection-api-us.realeyes.ai/v1/`

# API Endpoints

# 1. Detect Liveness

Analyzes an image to determine if it contains a live face or a spoofing attempt.

Endpoint: POST /v1/liveness-detection/detect

Request Body:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  }
}

Request Parameters:

image.bytes (string): Base64-encoded JPEG or PNG image
image.url (string, optional): URL of the image (alternative to bytes)

Response:

{
  "isLive": true,
  "confidence": 0.98,
  "spoofType": null,
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  }
}

Response Fields:

isLive (boolean): Whether the face is determined to be live
confidence (float): Liveness confidence score [0.0, 1.0] (higher is better)
spoofType (string, nullable): Type of spoof detected if isLive is false
- Possible values: "photo", "video", "mask", "deepfake", null
face: Detected face information
- confidence: Face detection confidence score [0.0, 1.0]
- boundingBox: Face location (X, Y, Width, Height in pixels)

cURL Example:

curl -X POST "https://liveness-detection-api-eu.realeyes.ai/v1/liveness-detection/detect" \
  -H "Authorization: ApiKey YWJjMTIzOnh5ejc4OQ==" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    }
  }'

# 2. Health Check

Check the API service health status.

Endpoint: GET /v1/healthz

Response:

"2026-01-27T10:30:45.1234567Z"

Response: ISO 8601 formatted UTC timestamp indicating the server is healthy.

cURL Example:

curl -X GET "https://liveness-detection-api-eu.realeyes.ai/v1/healthz" \
  -H "Authorization: ApiKey YWJjMTIzOnh5ejc4OQ=="

# Common Response Codes

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid image format, missing required fields, or invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Valid authentication but insufficient permissions
`500`	Internal Server Error - Server-side error during processing

# Swagger Documentation

Interactive API documentation is available via Swagger UI:

Last updated: 2026-01-27