# Realeyes Guide for Face Verification API

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

Version 1.0: Initial version.

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

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

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>

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.

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

The service requires an activation key.

Set:

ACTIVATION_KEY=<PROVIDED_ACTIVATION_KEY>

You need to request the activation key from Realeyes.

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

Alternatively one can use the following docker-compose.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

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.

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).

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:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "maxFaceCount": 10
}

Request Parameters:

Response Example:

{
  "faces": [
    {
      "confidence": 0.9876,
      "boundingBox": {
        "x": 120,
        "y": 80,
        "width": 200,
        "height": 250
      }
    }
  ],
  "unprocessedFaceCount": 0
}

Response Fields:

Example Request:

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

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:

{
  "image": {
    "bytes": "base64-encoded-image-string",
    "url": null
  },
  "maxFaceCount": 1
}

Request Parameters:

Response Example:

{
  "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:

Example Request:

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

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:

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

Request Parameters:

Response Example:

{
  "similarity": 85
}

Response Fields:

Example Request:

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