---
title: "Get Average Emotions"
method: GET
path: "/v2/videos/{video_id}/emotions/average"
tags: ["Video Emotion API"]
---

# Get Average Emotions

`GET /v2/videos/{video_id}/emotions/average`

Calculate and retrieve average emotion scores for a video with optional face filtering.

This endpoint computes the average emotion percentages across all frames in a video.
When a face_id is provided, it calculates the average emotions for only that specific face.

**Behavior:**
- **Without face_id**: Returns overall average emotion score for entire video (all faces combined)
- **With face_id**: Calculates average emotion scores for the specified face

**Parameters:**
- `video_id`: Unique identifier for the video
- `face_id`: (Optional) Calculate average emotions for only this face ID

**Response:**
Returns emotion scores as percentages (values sum to 1.0):
- `angry`: Percentage of anger emotion
- `disgust`: Percentage of disgust emotion
- `fear`: Percentage of fear emotion
- `happy`: Percentage of happiness emotion
- `sad`: Percentage of sadness emotion
- `surprise`: Percentage of surprise emotion
- `neutral`: Percentage of neutral emotion

**Use Cases:**
- **Overall video analysis**: Understand the general emotional tone of the entire video
- **Individual tracking**: Track emotional patterns of specific people throughout the video
- **Comparative analysis**: Compare emotional profiles between different faces in the same video

**Example Usage:**
- Overall average: `GET /v2/videos/123/emotions/average`
- Face-specific: `GET /v2/videos/123/emotions/average?face_id=1`

**Note:** Face-specific calculations require the face to appear in at least one frame.

## Path parameters

- `video_id` string, required — The unique video ID of the video for which average emotions are to be calculated

## Query parameters

- `face_id` integer, nullable — Optional face ID to calculate average emotions for a specific face

## Response `200`

Successful Response

- EmotionScores — Emotion scores representing the intensity of each emotion. All scores are non-negative floats (``ge=0``) — model intensities, not counts.
  - `angry` number — Score for angry
  - `contempt` number — Score for contempt
  - `disgust` number — Score for disgust
  - `fear` number — Score for fear
  - `happy` number — Score for happy
  - `neutral` number — Score for neutral
  - `sad` number — Score for sad
  - `surprise` number — Score for surprise

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai.md) · [All operations](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/imentiv/welcome-to-imentiv-ai/revisions/350e9cbcb623/schema)