Documentation

# Face Verification API

# Overview

The Face Verification API provides face detection, embedding extraction, and face comparison services for identity verification and authentication use cases.

The Face Verification API enables you to:

  • Detect faces in images with bounding boxes and confidence scores
  • Extract face embeddings from images for identity verification
  • Compare face embeddings to verify if two faces belong to the same person
  • Process multiple faces in a single image
  • Utilize high-accuracy AI models for face verification

# Base URLs

Region Base URL
EU https://face-verification-api-eu.realeyes.ai/v1/
US https://face-verification-api-us.realeyes.ai/v1/

# API Endpoints

# Detect Faces

Returns a list of detected faces on the provided image with their respective bounding boxes.

Endpoint: POST /v1/face-verification/detect-faces

Authentication: API Key or Bearer Token

Request Body:

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

Request Parameters:

Parameter Type Required Description
image object Yes The image to process
image.url string (nullable) No URL of a jpeg or png image
image.bytes string (nullable) No Base 64 string encoded binary jpeg or png image
maxFaceCount integer No Maximum number of faces to detect in the image

Response Example:

{
  "faces": [
    {
      "confidence": 0.9876,
      "boundingBox": {
        "x": 120,
        "y": 80,
        "width": 200,
        "height": 250
      }
    }
  ],
  "unprocessedFaceCount": 0
}

Response Fields:

Field Path Type Description
faces array (nullable) Faces found on the image
faces[].confidence number Face detection score with value range [0.0, 1.0] (higher is better)
faces[].boundingBox object Model for the bounding box of a detected face
faces[].boundingBox.x integer Horizontal position of the detected face bounding box
faces[].boundingBox.y integer Vertical position of the detected face bounding box
faces[].boundingBox.width integer Width of the detected face bounding box
faces[].boundingBox.height integer Height of the detected face bounding box
unprocessedFaceCount integer Number of faces found on the image but were not returned (because the max_faces request parameter filtered them out)

Example Request:

curl -X POST "https://face-verification-api-eu.realeyes.ai/v1/face-verification/detect-faces" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "maxFaceCount": 10
  }'

Response Codes:

  • 200 - Returns the detected faces results

# Get Face Embeddings

Returns a list of face embeddings for all the detected faces in the provided image.

Endpoint: POST /v1/face-verification/get-face-embeddings

Authentication: API Key or Bearer Token

Request Body:

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

Request Parameters:

Parameter Type Required Description
image object Yes The image to process
image.url string (nullable) No URL of a jpeg or png image
image.bytes string (nullable) No Base 64 string encoded binary jpeg or png image
maxFaceCount integer No Maximum number of faces to get the embedding on

Response Example:

{
  "faces": [
    {
      "face": {
        "confidence": 0.9876,
        "boundingBox": {
          "x": 120,
          "y": 80,
          "width": 200,
          "height": 250
        }
      },
      "embedding": [0.123, -0.456, 0.789]
    }
  ],
  "unprocessedFaceCount": 0
}

Response Fields:

Field Path Type Description
faces array (nullable) Faces found on the image
faces[].face object Model for face detection
faces[].face.confidence number Face detection score with value range [0.0, 1.0] (higher is better)
faces[].face.boundingBox object Model for the bounding box of a detected face
faces[].face.boundingBox.x integer Horizontal position of the detected face bounding box
faces[].face.boundingBox.y integer Vertical position of the detected face bounding box
faces[].face.boundingBox.width integer Width of the detected face bounding box
faces[].face.boundingBox.height integer Height of the detected face bounding box
faces[].embedding array (nullable) Face verification embedding of the face
unprocessedFaceCount integer Number of faces found on the image but were not calculated the embedding on (because the max_faces request parameter filtered them out)

Example Request:

curl -X POST "https://face-verification-api-eu.realeyes.ai/v1/face-verification/get-face-embeddings" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "maxFaceCount": 1
  }'

Response Codes:

  • 200 - Returns the face embeddings results

# Compare Face Embeddings

Returns the similarity between two face embeddings as an integer between 0 and 100.

Endpoint: POST /v1/face-verification/compare-face-embeddings

Authentication: API Key or Bearer Token

Request Body:

{
  "embedding1": [0.123, -0.456, 0.789],
  "embedding2": [0.125, -0.450, 0.792]
}

Request Parameters:

Parameter Type Required Description
embedding1 array (nullable) Yes Embedding to compare
embedding2 array (nullable) Yes Embedding to compare with

Response Example:

{
  "similarity": 85
}

Response Fields:

Name Type Description
similarity integer Similarity between the two embeddings with value range [-1, 100] (higher is better). Reject any matches where similarity is less than 70.

Threshold reference (computed using extensive in-the-wild datasets):
• 95 corresponds to FPR 1e-06 (or better)
• 90 corresponds to FPR 1e-05
• 80 corresponds to FPR 1e-4
• 70 corresponds to FPR 1e-3

Example Request:

curl -X POST "https://face-verification-api-eu.realeyes.ai/v1/face-verification/compare-face-embeddings" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding1": [0.123, -0.456, 0.789],
    "embedding2": [0.125, -0.450, 0.792]
  }'

Response Codes:

  • 200 - Returns the similarity result

# Health Check

Check the API health status.

Endpoint: GET /v1/healthz

Authentication: None required

Response Example:

2026-02-16T10:30:45Z

Response Fields:

Name Type Description
(response body) string The server UTC time in ISO 8601 format

Example Request:

curl -X GET "https://face-verification-api-eu.realeyes.ai/v1/healthz"

Response Codes:

  • 200 - API is healthy

# Common Response Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Valid authentication but account not found or insufficient permissions
404 Not Found - Resource not found
500 Internal Server Error

# Swagger Documentation

Interactive API documentation is available via Swagger UI:

Last updated: 2026-02-16