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
• Associate your own external keys (e.g. a customer or user identifier) with faces and look faces up by them
• Manage face recognition collections (create, retrieve, update, reset, delete)
• Utilize high-accuracy AI models with configurable match thresholds

For a conceptual overview of what a face collection is and how it relates to a Verification, see Face collection.

Base URLs

API Endpoints

Get Collection

Retrieves a single collection by its identifier.

Endpoint: GET /v1/collection/get

Authentication: API Key or Bearer Token

Query Parameters:

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:

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",
      "description": "Collection for employee verification",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-02-10T14:20:00Z"
    },
    {
      "collectionId": "employee-faces",
      "description": null,
      "createdAt": "2026-01-20T08:15:00Z",
      "updatedAt": "2026-01-20T08:15:00Z"
    }
  ]
}

Response Fields:

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:

Response Example:

{
  "collectionId": "new-collection"
}

Response Fields:

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:

Response Example:

{
  "collectionId": "my-collection"
}

Response Fields:

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

Reset Collection

Removes all indexed faces from a collection without deleting the collection itself. The collection (and its description) is preserved and remains usable; only the faces it contains — and any external key associations they had — are removed. This operation is irreversible.

Endpoint: DELETE /v1/collection/reset

Authentication: API Key or Bearer Token

Query Parameters:

Response Example:

{
  "collectionId": "my-collection"
}

Response Fields:

Example Request:

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

Response Codes:

• 200 - Collection reset (all faces removed)
• 400 - Validation failure
• 401 - Authentication failure
• 404 - Collection not found

Delete Collection

Deletes a collection by its identifier.

Endpoint: DELETE /v1/collection/delete

Authentication: API Key or Bearer Token

Query Parameters:

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:

Response Example:

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

Response Fields:

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:

Response Example:

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

Response Fields:

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:

Response Example:

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

Response Fields:

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. You can delete either by faceId or by externalKey — one of the two is required. When deleting by externalKey, every face associated with that key is removed. Deleting a face also removes any external key association it had.

Endpoint: DELETE /v1/face/delete

Authentication: API Key or Bearer Token

Query Parameters:

Response Example:

{}

Example Request (by face id):

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"

Example Request (by external key):

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

Response Codes:

• 200 - OK
• 400 - Bad Request (neither faceId nor externalKey provided, or an invalid external key)
• 401 - Unauthorized
• 404 - Not Found

External Key Management

External keys let you attach your own identifier (for example a customer id, user id or reference number) to a face. A face has at most one external key, while an external key maps to a single face by default — or to several faces when duplicates are explicitly allowed.

External keys are managed independently of indexing: the index and search-or-index endpoints never set them. After indexing a face, call set to associate a key with it.

Set External Key

Associates an external key with a face. Creates a new association or updates the existing one (a face's key is replaced when set again with a different key).

Endpoint: PUT /v1/external-key/set

Authentication: API Key or Bearer Token

Request Body:

{
  "collectionId": "my-collection",
  "faceId": "face_abc123xyz789",
  "externalKey": "user-123",
  "allowDuplicates": false
}

Request Parameters:

Response Example:

{
  "faceId": "face_abc123xyz789",
  "externalKey": "user-123",
  "result": "Created"
}

Response Fields:

Example Request:

curl -X PUT "https://face-recognition-api-eu.realeyes.ai/v1/external-key/set" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "my-collection",
    "faceId": "face_abc123xyz789",
    "externalKey": "user-123",
    "allowDuplicates": false
  }'

Response Codes:

• 200 - Association created or updated
• 400 - Validation failure, or the external key is already associated with a different face and allowDuplicates is false
• 401 - Unauthorized
• 404 - Collection not found

Get Face IDs by External Key

Returns all face ids associated with the specified external key in a collection.

Endpoint: GET /v1/external-key/get-face-ids

Authentication: API Key or Bearer Token

Query Parameters:

Response Example:

{
  "faceIds": ["face_abc123xyz789"]
}

Response Fields:

Example Request:

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

Response Codes:

• 200 - OK
• 400 - Validation failure
• 401 - Unauthorized
• 404 - Collection not found

Delete External Key Association

Removes external key associations. When faceId is omitted, every face associated with the external key is unlinked; otherwise only the single pair is removed. This only removes the key association — it does not delete the face itself (use Delete Face for that).

Endpoint: DELETE /v1/external-key/delete

Authentication: API Key or Bearer Token

Query Parameters:

Response Example:

{}

Example Request:

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

Response Codes:

• 200 - Associations removed (idempotent)
• 400 - Validation failure
• 401 - Unauthorized
• 404 - Collection not found

External Key Format

• Maximum length: 512 characters.
• Allowed characters: printable ASCII only (0x21–0x7E). Spaces, control characters and Unicode characters are rejected with 400.
• Recommended encoding: keep keys ASCII. If you need to embed richer identifiers (Unicode names, or values containing spaces or slashes), base64url-encode them on your side and store the encoded value (e.g. matching ^[A-Za-z0-9_-]{1,512}$).
• Why ASCII only: external keys are used as lookup keys and may appear in URLs and logs. Restricting to printable ASCII avoids URL-encoding ambiguity and Unicode normalization collisions, where two visually identical keys are not byte-for-byte equal and therefore do not match.

Use Cases

For end-to-end scenarios using this API — including registering a face and checking it later — see the Use Cases page.

Health Check

Check the API health status.

Endpoint: GET /v1/healthz

Authentication: None required

Response Example:

2026-02-16T10:30:45Z

Response Fields:

Example Request:

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

Response Codes:

• 200 - API is healthy

Common Response Codes

Swagger Documentation

Interactive API documentation is available via Swagger UI:

• EU: https://face-recognition-api-eu.realeyes.ai/swagger
• US: https://face-recognition-api-us.realeyes.ai/swagger

Last updated: 2026-06-08