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

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

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

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

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

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

---

*Last updated: 2026-02-16*