# Realeyes Guide for Demographic Estimation API

This guide presents the requirements for acquiring, running and using the docker image of the Demographic Estimation 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 demographicestimation <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 demographicestimation --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/demographic-estimation-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/demographic-estimation-api:latest

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

services:
  demographic-estimation-api:
    image: 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/demographic-estimation-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 Demographic Estimation API service provides REST API endpoints for age estimation and gender detection.

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

Estimates the age of faces detected in an image.

Endpoint: POST /v1/demographic-estimation/get-age

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.9987,
        "boundingBox": {
          "x": 120,
          "y": 80,
          "width": 200,
          "height": 250
        }
      },
      "age": {
        "prediction": 28.5,
        "uncertainty": 0.45
      }
    }
  ],
  "unprocessedFaceCount": 0
}

Response Fields:

Example Request:

curl -X POST "https://demographic-estimation-api-eu.realeyes.ai/v1/demographic-estimation/get-age" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "maxFaceCount": 5
  }'

Response Codes:

• 200 - Success
• 400 - Bad Request - Invalid image format, missing required fields, or invalid parameters
• 401 - Unauthorized - Missing or invalid authentication

Detects the gender of faces in an image.

Endpoint: POST /v1/demographic-estimation/get-gender

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.9987,
        "boundingBox": {
          "x": 120,
          "y": 80,
          "width": 200,
          "height": 250
        }
      },
      "gender": "Male"
    }
  ],
  "unprocessedFaceCount": 0
}

Response Fields:

Example Request:

curl -X POST "https://demographic-estimation-api-eu.realeyes.ai/v1/demographic-estimation/get-gender" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "maxFaceCount": 5
  }'

Response Codes:

• 200 - Success
• 400 - Bad Request - Invalid image format, missing required fields, or invalid parameters
• 401 - Unauthorized - Missing or invalid authentication