# Face Verification API

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

# Overview

The Face Verification API enables you to:

Extract face embeddings from images for identity verification
Compare face embeddings to verify if two faces belong to the same person
Detect faces with bounding boxes and confidence scores
Monitor API health status

# Base URLs

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

# API Endpoints

# Get Face Embeddings

Extract face embeddings from an image. Returns all detected faces with their bounding boxes and embeddings.

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

Authentication: API Key (X-API-Key header)

Request Body:

{
  "imageBase64": "base64-encoded-image-string",
  "maxFaceCount": 1
}

Request Parameters:

Parameter	Type	Required	Default	Description
`imageBase64`	string	Yes	-	Base64 encoded JPEG or PNG image
`maxFaceCount`	integer	No	1	Maximum number of faces to process

Response:

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

Response Fields:

Field	Type	Description
`faces`	array	List of detected faces with embeddings
`faces[].confidence`	float	Face detection confidence score [0.0, 1.0] (higher is better)
`faces[].boundingBox`	object	Face bounding box coordinates
`faces[].boundingBox.x`	integer	Horizontal position of the bounding box
`faces[].boundingBox.y`	integer	Vertical position of the bounding box
`faces[].boundingBox.width`	integer	Width of the bounding box
`faces[].boundingBox.height`	integer	Height of the bounding box
`faces[].embedding`	float[]	Face embedding vector (float array)
`unprocessedFaceCount`	integer	Number of faces detected but not processed (due to maxFaceCount limit)

Example Request:

curl -X POST "https://face-verification-api-eu.realeyes.ai/face-verification/get-face-embeddings" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageBase64": "/9j/4AAQSkZJRgABAQEAYABgAAD...",
    "maxFaceCount": 1
  }'

Response Codes:

200 - Success
400 - Bad Request (invalid image format)
401 - Unauthorized (invalid or missing API key)

# Compare Face Embeddings

Compare two face embeddings to determine if they belong to the same person.

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

Authentication: API Key (X-API-Key header)

Request Body:

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

Request Parameters:

Parameter	Type	Required	Description
`embedding1`	float[]	Yes	First face embedding to compare
`embedding2`	float[]	Yes	Second face embedding to compare

Response:

{
  "similarity": 0.8542
}

Response Fields:

Field	Type	Description
`similarity`	float	Cosine similarity score [-1.0, 1.0] (higher is better)

Similarity Score Interpretation:

Score Range	Interpretation
`> 0.7`	High similarity - likely the same person
`0.4 - 0.7`	Medium similarity - uncertain match
`< 0.4`	Low similarity - likely different persons

Example Request:

curl -X POST "https://face-verification-api-eu.realeyes.ai/face-verification/compare-face-embeddings" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding1": [0.123, -0.456, 0.789],
    "embedding2": [0.125, -0.450, 0.792]
  }'

Response Codes:

200 - Success
401 - Unauthorized (invalid or missing API key)

# Health Check

Check the API health status.

Endpoint: GET /face-verification/ping

Authentication: API Key (X-API-Key header)

Response:

{
  "status": "healthy"
}

Example Request:

curl -X GET "https://face-verification-api-eu.realeyes.ai/face-verification/ping" \
  -H "X-API-Key: your-api-key-here"

Response Codes:

200 - API is healthy
401 - Unauthorized (invalid or missing API key)

# Common Response Codes

Status Code	Description
`400`	Bad Request - Invalid input parameters or image format
`401`	Unauthorized - Invalid or missing API key
`500`	Internal Server Error - Server-side processing error

# Swagger Documentation

Interactive API documentation is available via Swagger UI: