# Face Recognition API

# Overview

The Face Recognition API provides AI-powered face recognition and management capabilities for building secure identity verification systems.

The Face Recognition API enables you to:

Search for matching faces in your collections
Index new faces to collections for future recognition
Automatically search and index if not found (duplicate detection)
Delete faces from collections
Manage face recognition collections (create, retrieve, update, delete)
Utilize high-accuracy AI models with configurable match thresholds

# Base URLs

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

# API Endpoints

# Get Collection

Retrieves a single collection by its identifier.

Endpoint: GET /v1/collection/get

Authentication: API Key or Bearer Token

Query Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The collection identifier

Response Example:

{
  "recognitionCollection": {
    "collectionId": "my-collection",
    "description": "Collection for employee verification",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-02-10T14:20:00Z"
  }
}

Response Fields:

Field Path	Type	Description
`recognitionCollection`	object	The collection details
`recognitionCollection.collectionId`	string (nullable)	Identifier of the collection
`recognitionCollection.description`	string (nullable)	Optional textual description
`recognitionCollection.createdAt`	string	UTC timestamp when the collection was created
`recognitionCollection.updatedAt`	string	UTC timestamp when the collection was last updated

Example Request:

curl -X GET "https://face-recognition-api-eu.realeyes.ai/v1/collection/get?collectionId=my-collection" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"

Response Codes:

200 - Collection found
400 - Validation failure
401 - Authentication failure
404 - Collection not found

# Get All Collections

Lists all collections belonging to the authenticated account.

Endpoint: GET /v1/collection/get-all

Authentication: API Key or Bearer Token

Response Example:

{
  "collections": [
    {
      "collectionId": "my-collection",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-02-10T14:20:00Z"
    },
    {
      "collectionId": "employee-faces",
      "createdAt": "2026-01-20T08:15:00Z",
      "updatedAt": "2026-01-20T08:15:00Z"
    }
  ]
}

Response Fields:

Field Path	Type	Description
`collections`	array (nullable)	Collections returned for the account (may be empty)
`collections[].collectionId`	string (nullable)	Identifier of the collection
`collections[].createdAt`	string	UTC timestamp when the collection was created
`collections[].updatedAt`	string	UTC timestamp when the collection was last updated

Example Request:

curl -X GET "https://face-recognition-api-eu.realeyes.ai/v1/collection/get-all" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"

Response Codes:

200 - Collections returned
400 - Validation failure
401 - Authentication failure

# Create Collection

Creates a new recognition collection.

Endpoint: POST /v1/collection/create

Authentication: API Key or Bearer Token

Request Body:

{
  "collectionId": "new-collection",
  "description": "Collection for customer verification"
}

Request Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	Unique identifier for the collection (max length 512)
`description`	string (nullable)	No	Optional description (max length 1024)

Response Example:

{
  "collectionId": "new-collection"
}

Response Fields:

Name	Type	Description
`collectionId`	string (nullable)	Identifier of the created collection

Example Request:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/collection/create" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "new-collection",
    "description": "Collection for customer verification"
  }'

Response Codes:

200 - Collection created successfully
400 - Validation failure
401 - Authentication failure
409 - Collection already exists

# Update Collection

Updates an existing collection (only description is mutable).

Endpoint: PUT /v1/collection/update

Authentication: API Key or Bearer Token

Request Body:

{
  "collectionId": "my-collection",
  "description": "Updated description for my collection"
}

Request Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	Identifier of the collection to update
`description`	string (nullable)	No	New description (max length 1024)

Response Example:

{
  "collectionId": "my-collection"
}

Response Fields:

Name	Type	Description
`collectionId`	string (nullable)	Identifier of the updated collection

Example Request:

curl -X PUT "https://face-recognition-api-eu.realeyes.ai/v1/collection/update" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "my-collection",
    "description": "Updated description for my collection"
  }'

Response Codes:

200 - Collection updated
400 - Validation failure
401 - Authentication failure

# Delete Collection

Deletes a collection by its identifier.

Endpoint: DELETE /v1/collection/delete

Authentication: API Key or Bearer Token

Query Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The collection identifier

Response Example:

{}

Example Request:

curl -X DELETE "https://face-recognition-api-eu.realeyes.ai/v1/collection/delete?collectionId=my-collection" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"

Response Codes:

200 - Collection deleted (idempotent)
400 - Validation failure
401 - Authentication failure

# Search Face

Search for a face in a specified collection. Returns the face ID if a match is found. The faces on the images should be in an upright position. Sideways or upside-down faces are not supported.

Endpoint: POST /v1/face/search

Authentication: API Key or Bearer Token

Request Body:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "collectionId": "my-collection",
  "faceMatchThreshold": 80
}

Request Parameters:

Parameter	Type	Required	Description
`image`	object	Yes	The image to search
`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
`collectionId`	string (nullable)	Yes	The id of the collection to search against
`faceMatchThreshold`	integer	No	Specifies the minimum confidence in the face match to return. Default value: 80. Valid range: 0-100. Threshold reference (computed using extensive in-the-wild datasets): • 95 corresponds to FPR 1e-06 • 90 corresponds to FPR 1e-05 • 80 corresponds to FPR 1e-4 • 70 corresponds to FPR 1e-3

Response Example:

{
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  },
  "faceId": "face_abc123xyz789",
  "hasFace": true,
  "unprocessedFaceCount": 0
}

Response Fields:

Field Path	Type	Description
`face`	object	Detected face information
`face.confidence`	number	Face detection score with value range [0.0, 1.0] (higher is better)
`face.boundingBox`	object	Model for the bounding box of a detected face
`face.boundingBox.x`	integer	Horizontal position of the detected face bounding box
`face.boundingBox.y`	integer	Vertical position of the detected face bounding box
`face.boundingBox.width`	integer	Width of the detected face bounding box
`face.boundingBox.height`	integer	Height of the detected face bounding box
`faceId`	string (nullable)	The id of the face
`hasFace`	boolean	Indicates whether a face was found in the image
`unprocessedFaceCount`	integer	In case more than one face was detected, only the dominant face will be used for the recognition. This count indicates how many faces were not processed

Example Request:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/face/search" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "collectionId": "my-collection",
    "faceMatchThreshold": 80
  }'

Response Codes:

200 - OK
400 - Bad Request
401 - Unauthorized
404 - Not Found

# Index Face

Index a new face into a specified collection. Returns the generated face ID. The faces on the images should be in an upright position. Sideways or upside-down faces are not supported.

Endpoint: POST /v1/face/index

Authentication: API Key or Bearer Token

Request Body:

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

Request Parameters:

Parameter	Type	Required	Description
`image`	object	Yes	The image to index
`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
`collectionId`	string (nullable)	Yes	The id of the collection to index the face into

Response Example:

{
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  },
  "faceId": "face_new456def012",
  "hasFace": true,
  "unprocessedFaceCount": 0
}

Response Fields:

Field Path	Type	Description
`face`	object	Detected face information
`face.confidence`	number	Face detection score with value range [0.0, 1.0] (higher is better)
`face.boundingBox`	object	Model for the bounding box of a detected face
`face.boundingBox.x`	integer	Horizontal position of the detected face bounding box
`face.boundingBox.y`	integer	Vertical position of the detected face bounding box
`face.boundingBox.width`	integer	Width of the detected face bounding box
`face.boundingBox.height`	integer	Height of the detected face bounding box
`faceId`	string (nullable)	The id of the face
`hasFace`	boolean	Indicates whether a face was found in the image
`unprocessedFaceCount`	integer	In case more than one face was detected, only the dominant face will be used for the recognition. This count indicates how many faces were not processed

Example Request:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/face/index" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "collectionId": "my-collection"
  }'

Response Codes:

200 - OK
400 - Bad Request
401 - Unauthorized
404 - Not Found

# Search or Index Face

Search for a face within a collection or index the face if not found. Useful for duplicate detection. The faces on the images should be in an upright position. Sideways or upside-down faces are not supported.

Endpoint: POST /v1/face/search-or-index

Authentication: API Key or Bearer Token

Request Body:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "collectionId": "my-collection",
  "faceMatchThreshold": 80
}

Request Parameters:

Parameter	Type	Required	Description
`image`	object	Yes	The image to search or index
`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
`collectionId`	string (nullable)	Yes	The id of the collection to search against
`faceMatchThreshold`	integer	No	Specifies the minimum confidence in the face match to return. Default value: 80. Valid range: 0-100. Threshold reference (computed using extensive in-the-wild datasets): • 95 corresponds to FPR 1e-06 • 90 corresponds to FPR 1e-05 • 80 corresponds to FPR 1e-4 • 70 corresponds to FPR 1e-3

Response Example:

{
  "face": {
    "confidence": 0.9987,
    "boundingBox": {
      "x": 120,
      "y": 80,
      "width": 200,
      "height": 250
    }
  },
  "faceId": "face_abc123xyz789",
  "hasFace": true,
  "unprocessedFaceCount": 0,
  "resultSource": "Search"
}

Response Fields:

Field Path	Type	Description
`face`	object	Detected face information
`face.confidence`	number	Face detection score with value range [0.0, 1.0] (higher is better)
`face.boundingBox`	object	Model for the bounding box of a detected face
`face.boundingBox.x`	integer	Horizontal position of the detected face bounding box
`face.boundingBox.y`	integer	Vertical position of the detected face bounding box
`face.boundingBox.width`	integer	Width of the detected face bounding box
`face.boundingBox.height`	integer	Height of the detected face bounding box
`faceId`	string (nullable)	The id of the face
`hasFace`	boolean	Indicates whether a face was found in the image
`unprocessedFaceCount`	integer	In case more than one face was detected, only the dominant face will be used for the recognition. This count indicates how many faces were not processed
`resultSource`	string	Specifies the source of a result in an operation. Possible values: "None", "Search", "Index"

Example Request:

curl -X POST "https://face-recognition-api-eu.realeyes.ai/v1/face/search-or-index" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "collectionId": "my-collection",
    "faceMatchThreshold": 80
  }'

Response Codes:

200 - OK
400 - Bad Request
401 - Unauthorized
404 - Not Found

# Delete Face

Delete a face from the specified collection. The faces on the images should be in an upright position. Sideways or upside-down faces are not supported.

Endpoint: DELETE /v1/face/delete

Authentication: API Key or Bearer Token

Query Parameters:

Parameter	Type	Required	Description
`collectionId`	string	Yes	The id of the collection
`faceId`	string	Yes	The id of the face to be deleted

Response Example:

{}

Example Request:

curl -X DELETE "https://face-recognition-api-eu.realeyes.ai/v1/face/delete?collectionId=my-collection&faceId=face_abc123xyz789" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE"

Response Codes:

200 - OK
400 - Bad Request
401 - Unauthorized
404 - Not Found

# 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-recognition-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

# Face Recognition API

# Overview

# Base URLs

# API Endpoints

# Get Collection

# Get All Collections

# Create Collection

# Update Collection

# Delete Collection

# Search Face

# Index Face

# Search or Index Face

# Delete Face

# Health Check

# Common Response Codes

# Swagger Documentation

See also