# Emotion & Attention API

# Overview

The Emotion & Attention API provides AI-powered facial emotion detection and attention analysis for understanding user engagement and emotional states. This API analyzes facial expressions to detect emotions, attention levels, and facial landmarks in real-time.

Key Features:

Emotion Detection: Identify multiple emotions (happiness, confusion, surprise, contempt, disgust, empathy)
Attention Analysis: Determine if a person is attentive and has eyes on screen
Facial Landmarks: Extract detailed facial landmark positions in 2D and 3D space
Presence Detection: Detect face and person presence in images
Real-time Analysis: Fast processing for seamless user experience
Regional Deployment: Available in multiple regions for low latency

# 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

# 1. Detect Emotions & Attention

Analyzes an image to detect emotions, attention state, and facial landmarks for the dominant face.

Endpoint: POST /v1/emotion-attention/detect

Request Body:

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

Request Parameters:

image.bytes (string): Base64-encoded JPEG or PNG image
image.url (string, optional): URL of the image (alternative to bytes)

Response:

{
  "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
    },
    "points2D": [
      { "x": 310.2, "y": 235.6 },
      { "x": 330.8, "y": 236.1 }
    ],
    "points3D": [
      { "x": 0.12, "y": -0.05, "z": 0.98 },
      { "x": 0.15, "y": -0.04, "z": 0.97 }
    ]
  }
}

Response Fields:

EmotionsAttention Object:

hasFace (boolean, nullable): Whether a face is detected in the image
presence (boolean, nullable): Whether a person is present in the image
eyesOnScreen (boolean, nullable): Whether the person's eyes are on the screen
attention (boolean, nullable): Whether the person is attentive
confusion (boolean, nullable): Whether confusion emotion is detected
contempt (boolean, nullable): Whether contempt emotion is detected
disgust (boolean, nullable): Whether disgust emotion is detected
happy (boolean, nullable): Whether happiness emotion is detected
empathy (boolean, nullable): Whether empathy emotion is detected
surprise (boolean, nullable): Whether surprise emotion is detected

Note: null values indicate that the state could not be determined reliably.

Landmarks Object:

scale (double): Scale of the face
roll (double): Roll pose angle (head tilt left/right)
yaw (double): Yaw pose angle (head turn left/right)
pitch (double): Pitch pose angle (head tilt up/down)
translate (Point2D): Position of the head center in image coordinates
points2D (array): Array of 2D facial landmark points (x, y coordinates)
points3D (array): Array of 3D facial landmark points (x, y, z coordinates)

cURL Example:

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

# 2. Health Check

Check the API service health status.

Endpoint: GET /v1/healthz

# Common Response Codes

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid image format, missing required fields, or invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Valid authentication but insufficient permissions
`500`	Internal Server Error - Server-side error during processing

# Swagger Documentation

Interactive API documentation is available via Swagger UI:

Last updated: 2026-01-27