# 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