Documentation

Emotion & Attention API

Overview

The Emotion & Attention API provides AI-powered facial emotion detection and attention analysis for understanding user engagement and emotional states.

The Emotion & Attention API enables you to:

  • Detect multiple emotions (happiness, confusion, surprise, contempt, disgust, empathy)
  • Analyze attention levels and determine if eyes are on screen
  • Extract detailed facial landmark positions in 2D and 3D space
  • Detect face and person presence in images

Base URLs

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

API Endpoints

Detect Emotions and Attention

Returns whether a face was detected and, for the dominant face in the image, the detected emotions, attention state, and facial landmarks.

Endpoint: POST /v1/emotion-attention/detect

Authentication: API Key or Bearer Token

Request Body:

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

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

Response Example:

{
  "emotionsAttention": {
    "hasFace": true,
    "presence": true,
    "eyesOnScreen": true,
    "attention": true,
    "confusion": false,
    "contempt": false,
    "disgust": false,
    "happy": true,
    "empathy": false,
    "surprise": false
  },
  "landmarks": {
    "scale": 1.23,
    "roll": -2.5,
    "yaw": 5.3,
    "pitch": -1.2,
    "translate": {
      "x": 320.5,
      "y": 240.8
    },
    "landmarks2D": [
      { "x": 310.2, "y": 235.6 },
      { "x": 330.8, "y": 236.1 }
    ],
    "landmarks3D": [
      { "x": 0.12, "y": -0.05, "z": 0.98 },
      { "x": 0.15, "y": -0.04, "z": 0.97 }
    ],
    "isGood": true
  }
}

Response Fields:

Field Path Type Description
emotionsAttention object Results of analyzing image for facial presence, attention, and emotional states
emotionsAttention.hasFace boolean (nullable) Whether a face is detected in the image (null means it could not be determined reliably)
emotionsAttention.presence boolean (nullable) Whether a person is present in the image (null means it could not be determined reliably)
emotionsAttention.eyesOnScreen boolean (nullable) Whether the person's eyes are on the screen (null means it could not be determined reliably)
emotionsAttention.attention boolean (nullable) Whether the person is attentive (null means it could not be determined reliably)
emotionsAttention.confusion boolean (nullable) Whether confusion emotion is detected (null means it could not be determined reliably)
emotionsAttention.contempt boolean (nullable) Whether contempt is detected (null means it could not be determined reliably)
emotionsAttention.disgust boolean (nullable) Whether disgust is detected (null means it could not be determined reliably)
emotionsAttention.happy boolean (nullable) Whether happiness is detected (null means it could not be determined reliably)
emotionsAttention.empathy boolean (nullable) Whether empathy is detected (null means it could not be determined reliably)
emotionsAttention.surprise boolean (nullable) Whether surprise is detected (null means it could not be determined reliably)
landmarks object Result of facial landmark detection, including pose, scale, and landmark positions in 2D and 3D space
landmarks.scale number Scale of the face
landmarks.roll number Roll pose angle
landmarks.yaw number Yaw pose angle
landmarks.pitch number Pitch pose angle
landmarks.translate object Translation coordinates in 2D space
landmarks.translate.x number The X axis coordinate of the head center in image space
landmarks.translate.y number The Y axis coordinate of the head center in image space
landmarks.landmarks2D array (nullable) Position of the 49 landmarks, in image coordinates
landmarks.landmarks2D[].x number The X axis coordinate of a landmark point in 2D space
landmarks.landmarks2D[].y number The Y axis coordinate of a landmark point in 2D space
landmarks.landmarks3D array (nullable) Position of the 49 landmarks, in an un-scaled face-centered 3D space
landmarks.landmarks3D[].x number The X axis coordinate of a landmark point in 3D space
landmarks.landmarks3D[].y number The Y axis coordinate of a landmark point in 3D space
landmarks.landmarks3D[].z number The Z axis coordinate of a landmark point in 3D space
landmarks.isGood boolean Whether the tracking is good quality or not

Example Request:

curl -X POST "https://emotion-attention-api-eu.realeyes.ai/v1/emotion-attention/detect" \
  -H "Authorization: ApiKey API-KEY-FROM-DEV-CONSOLE" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "bytes": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    }
  }'

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://emotion-attention-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:

The OpenAPI specification is available at:

Last updated: 2026-08-04