# 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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:**

```json
{
  "collectionId": "new-collection"
}
```

**Response Fields:**

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

**Example Request:**

```bash
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:**

```json
{
  "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:**

```json
{
  "collectionId": "my-collection"
}
```

**Response Fields:**

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

**Example Request:**

```bash
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:**

```json
{}
```

**Example Request:**

```bash
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:**

```json
{
  "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.<br><br>**Threshold reference** (computed using extensive in-the-wild datasets):<br>• **95** corresponds to FPR 1e-06<br>• **90** corresponds to FPR 1e-05<br>• **80** corresponds to FPR 1e-4<br>• **70** corresponds to FPR 1e-3 |

**Response Example:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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.<br><br>**Threshold reference** (computed using extensive in-the-wild datasets):<br>• **95** corresponds to FPR 1e-06<br>• **90** corresponds to FPR 1e-05<br>• **80** corresponds to FPR 1e-4<br>• **70** corresponds to FPR 1e-3 |

**Response Example:**

```json
{
  "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:**

```bash
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:**

```json
{}
```

**Example Request:**

```bash
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:**

```bash
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:

- **EU**: [https://face-recognition-api-eu.realeyes.ai/swagger](https://face-recognition-api-eu.realeyes.ai/swagger)
- **US**: [https://face-recognition-api-us.realeyes.ai/swagger](https://face-recognition-api-us.realeyes.ai/swagger)

---

*Last updated: 2026-02-16*