--- layout: page --- # Realeyes Guide for Emotion Attention API ## Overview This guide presents the requirements for acquiring, running and using the docker image of the Emotion Attention API service. --- ## Changelog **Version 1.0:** Initial version. --- ## Accessing and pulling the latest docker image You must do the first 2 steps only once per user/computer. ### Prerequisites It is required that you have AWS CLI installed. This command is supported using the latest version of AWS CLI version 2 or in v1.17.10 or later of AWS CLI version 1. See how to: [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) ### Configure AWS credential profile You should have previously received your access key ID and Secret Access Key from Realeyes. Please use them here: ``` aws configure --profile emotionattention AWS Access Key ID [None]: AWS Secret Access Key [None]: Default region name [None]: ``` ### Get authorization token and pass it to docker login ``` aws ecr get-login-password --profile emotionattention --region eu-west-1 | docker login --username AWS --password-stdin 249265253269.dkr.ecr.eu-west-1.amazonaws.com ``` The get-login-password command retrieves and displays an authentication token using the GetAuthorizationToken API -- you will use this token to authenticate to an Amazon ECR registry. You can pass the authorization token to the login command of the container client of your preference, such as the Docker CLI. After you have authenticated to an Amazon ECR registry with this command, you can use the client to pull images from that registry as long as your IAM principal has access to do so before the token expires. **NOTE:** The authorization token is valid for 12 hours. ### Pull the latest docker image ``` docker pull 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/emotion-attention-api:latest ``` --- ## Running the image The service requires an activation key. Set: ``` ACTIVATION_KEY= ``` You need to request the activation key from Realeyes. ### Run with docker Run the container with the following command: ``` docker run --rm -ti -p 8080:8080/tcp \ -e ACTIVATION_KEY= \ --read-only \ --pids-limit=128 \ --security-opt=no-new-privileges \ --memory=16G \ 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/emotion-attention-api:latest ``` ### Run with docker compose Alternatively one can use the following docker-compose.yaml: ```yaml services: emotion-attention-api: image: 249265253269.dkr.ecr.eu-west-1.amazonaws.com/verifeye/emotion-attention-api:latest environment: - ACTIVATION_KEY= ports: - 8080:8080 read_only: true security_opt: - "no-new-privileges" deploy: resources: limits: pids: 128 memory: 16G ``` --- ## Interactive API Documentation (Swagger UI) Once the service is running, you can access the interactive API documentation at: ``` http://localhost:8080/swagger/index.html ``` This Swagger UI provides a **living documentation** of the API where you can: - Browse all available endpoints with their detailed descriptions - View request/response schemas and example payloads - **Try out the API directly from your browser** – send real requests and see the responses in real-time - Explore error codes and response formats This is the recommended way to get familiar with the API and test your integration during development. --- ## API overview The Emotion Attention API service provides REST API endpoints for emotion and attention detection. Below is the outline of the API, while a more detailed documentation is available on the Swagger UI (see above). ### 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