---
layout: page
---

# Realeyes Guide for Face Verification API

## Overview

This guide presents the requirements for acquiring, running and using the docker image of the Face Verification API service.

---

## Changelog

**Version 1.0:** Initial version.

---

## Accessing and pulling the latest docker image

You must do the first 2 steps only once per user/computer.

### Prerequisites

It is required that you have AWS CLI installed. This command is supported using the latest version of AWS CLI version 2 or in v1.17.10 or later of AWS CLI version 1.

See how to: [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)

### Configure AWS credential profile

You should have previously received your access key ID and Secret Access Key from Realeyes. Please use them here:

```
aws configure --profile faceverification <HIT ENTER>
    AWS Access Key ID [None]: <ENTER YOUR ACCESS KEY ID>
    AWS Secret Access Key [None]: <ENTER YOUR SECRET ACCESS KEY>
    Default region name [None]: <LEAVE BLANK, JUST HIT ENTER>
```

### Get authorization token and pass it to docker login

```
aws ecr get-login-password --profile faceverification --region eu-west-1 | docker login --username AWS --password-stdin 249265253269.dkr.ecr.eu-west-1.amazonaws.com
```

The get-login-password command retrieves and displays an authentication token using the GetAuthorizationToken API -- you will use this token to authenticate to an Amazon ECR registry. You can pass the authorization token to the login command of the container client of your preference, such as the Docker CLI. After you have authenticated to an Amazon ECR registry with this command, you can use the client to pull images from that registry as long as your IAM principal has access to do so before the token expires. **NOTE:** The authorization token is valid for 12 hours.

### Pull the latest docker image

```
docker pull 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/face-verification-api:latest
```

---

## Running the image

The service requires an activation key.

Set:

```
ACTIVATION_KEY=<PROVIDED_ACTIVATION_KEY>
```

You need to request the activation key from Realeyes.

### Run with docker

Run the container with the following command:

```
docker run --rm -ti -p 8080:8080/tcp \
    -e ACTIVATION_KEY=<PROVIDED_ACTIVATION_KEY> \
    --read-only \
    --pids-limit=128 \
    --security-opt=no-new-privileges \
    --memory=16G \
    249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/face-verification-api:latest
```

### Run with docker compose

Alternatively one can use the following docker-compose.yaml:

```yaml
services:
  face-verification-api:
    image: 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/face-verification-api:latest
    environment:
      - ACTIVATION_KEY=<PROVIDED_ACTIVATION_KEY>
    ports:
      - 8080:8080
    read_only: true
    security_opt:
      - "no-new-privileges"
    deploy:
      resources:
        limits:
          pids: 128
          memory: 16G
```

---

## Interactive API Documentation (Swagger UI)

Once the service is running, you can access the interactive API documentation at:

```
http://localhost:8080/swagger/index.html
```

This Swagger UI provides a **living documentation** of the API where you can:
- Browse all available endpoints with their detailed descriptions
- View request/response schemas and example payloads
- **Try out the API directly from your browser** – send real requests and see the responses in real-time
- Explore error codes and response formats

This is the recommended way to get familiar with the API and test your integration during development.

---

## API overview

The Face Verification API service provides the following REST API endpoints:

- detect-faces
- get-face-embeddings
- compare-face-embeddings

Below is the outline of the API, while a more detailed documentation is available on the Swagger UI (see above).

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

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

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

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

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

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

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

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

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

**Example Request:**

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