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

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

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

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

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

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

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

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

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

---

*Last updated: 2026-02-16*