Documentation

# Demographic Estimation API

# Overview

The Demographic Estimation API provides AI-powered age estimation and gender detection services for faces in images.

The Demographic Estimation API enables you to:

  • Estimate the age of detected faces with uncertainty scores
  • Detect the gender of faces in images
  • Process multiple faces in a single image
  • Utilize high-accuracy AI models for demographic analysis

# Base URLs

Region Base URL
EU https://demographic-estimation-api-eu.realeyes.ai/v1/
US https://demographic-estimation-api-us.realeyes.ai/v1/

# API Endpoints

# Get Age

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:

Parameter Type Required Description
image object Yes Image data provided as URL or Base64 encoded bytes
image.url string (nullable) No URL of a JPEG or PNG image
image.bytes string (nullable) No Base64 encoded binary JPEG or PNG image
maxFaceCount integer No Maximum number of faces to be processed (default: 1)

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:

Field Path Type Description
faces array (nullable) The faces that were processed and their age estimation results
faces[].face object Face detection information
faces[].face.confidence number Face detection score with value range [0.0, 1.0] (higher is better)
faces[].face.boundingBox object Bounding box of the 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[].age object Age estimation information
faces[].age.prediction number (nullable) Estimated age
faces[].age.uncertainty number (nullable) Uncertainty score of the estimation with value range [0.0, infinity], we recommend rejecting everything higher than 1.0
unprocessedFaceCount integer The number of faces that were not processed due to the maximum face count limit

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

# Get Gender

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:

Parameter Type Required Description
image object Yes Image data provided as URL or Base64 encoded bytes
image.url string (nullable) No URL of a JPEG or PNG image
image.bytes string (nullable) No Base64 encoded binary JPEG or PNG image
maxFaceCount integer No Maximum number of faces to be processed (default: 1)

Response Example:

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

Response Fields:

Field Path Type Description
faces array (nullable) The faces that were processed and their gender detection results
faces[].face object Face detection information
faces[].face.confidence number Face detection score with value range [0.0, 1.0] (higher is better)
faces[].face.boundingBox object Bounding box of the 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[].gender string Detected gender (Male or Female)
unprocessedFaceCount integer The number of faces that were not processed due to the maximum face count limit

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

# Health Check

Check the API health status.

Endpoint: GET /v1/healthz

Authentication: None required

Response Example:

2026-02-16T13:45:30.1234567Z

Response Fields:

Name Type Description
(response body) string The server UTC time in ISO 8601 format

Example Request:

curl -X GET "https://demographic-estimation-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
500 Internal Server Error

# Swagger Documentation

Interactive API documentation is available via Swagger UI:

Last updated: 2026-02-16