1. Overview

This guide presents the requirements for integrating the Demographic Estimation API service.

2. Service authentication

Realeyes provides an account hash and an API key to authenticate API requests.

You can get your credentials by logging into the Developers Portal, if you don't have an account, you can sign up for here

3. Available Regional Services

Our service runs in two regions (Europe and USA) to meet the highest levels of security, compliance, and data protection.

You will need to call the corresponding regional endpoints (EU, US) to successfully manage a project or audit the verifications.

4. Sample code

Please check our requirements for the input image on this link.

The API endpoints are segmented by region as follows:

The following sample code shows how to call the age estimation. Age estimation is a process that uses machine learning to predict the age of a person based on their facial features. The API provides a simple way to estimate the age of a person or people in an image.

The request method is POST /v1/demogpraphic-estimation/get-age An API reference for this functionality is also available per this link.

The API requires additional information to process requests. It includes:

  • Authorization header (X-API-Key): Account API-Key .The API Key is avialable in the Developers Portal.
  • Request Body: 
    {
  "imageBase64": "string",
  "maxFaceCount": number
}

Here's a breakdown of the request:

  • imageBase64: The Base64 encoded image with the face(s) that you want to estimate the age of.
  • maxFaceCount: The maximum number of faces to detect in the image. The default value is 1.

The response is the following:

{
  "faces": [
    {
      "face": {
        "confidence": number,
        "boundingBox": {
          "x": number,
          "y": number,
          "width": number,
          "height": number
        }
      },
      "age": {
        "prediction": number,
        "uncertainty": number
      }
    }
  ],
  "unprocessedFaceCount": number
}

The API response contains the faces property, which holds the face detection and age estimation information for each face detected in the image.

A face object contains the following properties:

  • confidence: The confidence score of face detection [0.0, 1.0] (higher is better).
  • boundingBox: The bounding box of the detected face (X, Y coordinates, width, and height).

An age object contains the following properties:

  • prediction: The estimated age of the face.
  • uncertainty: The uncertainty score of the estimation with value range [0.0, infinity], we recommend rejecting everything higher than 1.0. Values higher than this can be indicative of a problem with the image quality.

Besides the face objects, the response also contains the unprocessedFaceCount property, which indicates the number of faces that were not processed due to the maximum face count limit.


import requests
import json

url = "https://demographic-estimation-api-eu.realeyesit.com/v1/demogpraphic-estimation/get-age"
api_key = "YOUR API KEY"

headers = {
    "X-Api-Key": api_key,
    "Content-Type": "application/json",
}

request = {
    "imageBase64": "base64,/9j/4TsvRXhpZgAASU...",
    "maxFaceCount": 1
}

response = requests.post(url, headers=headers, data=json.dumps(request))

if response.status_code == 200:
    print(response.json())
else:
    print(response.status_code, response.text)
Warning

The API is a regional service, you need to send requests to the correct endpoint. The above examples are using the European endpoint.

5. Next steps

For the full list of available endpoints and their parameters, please refer to the API reference.