---
title: "Get Video Emotion Insights"
method: GET
path: "/v1/videos/{video_id}"
tags: ["Video Emotion API"]
---

# Get Video Emotion Insights

`GET /v1/videos/{video_id}`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v1/videos/{video_id}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.read`

Get a single video details by ID

## Path parameters

- `video_id` string, required: The unique ID of the video to be fetched

## Response `200`

Successful Response

- VideoResponse: Model representing detailed video metadata and analysis. Attributes: title (Optional[str]): Title of the video. description (str): Description of the video. id (str): Unique video identifier. audio_id (str): Related audio ID if extracted. model_id (str): Model used to process video. emotions_list (List[str]): List of possible emotions. url (str): Original video file url faces (Optional[ListOfFaces]): Detected faces in the video. annotated_video_mp4 (Any): Processed video with annotations. summary (str): Summary text of the video. total_frames_count (Optional[int]): Total number of frames. fps (Optional[float]): Frames per second. height (Optional[float]): Height of the video. width (Optional[float]): Width of the video. status (str): Current processing status. created_at (str): Creation timestamp. thumbnail_image (str): URL or data of the thumbnail image. text_id (str): Linked text analysis ID.
  - `title` string
  - `description` string
  - `id` string, required
  - `audio_id` string
  - `model_id` string
  - `emotions_list` string[]
  - `url` string
  - `faces` ListOfFaces: Model representing a collection of faces. Attributes: faces (List[Faces]): List of detected or named faces.
    - `faces` Faces[], required
      - `image` string
      - `name` string, nullable
      - `face_id` integer, required
      - `confidence` number, nullable: Name-assignment confidence. For source 'ocr', the winning share of votes; for 'driver_selection', the strength of that selection. Not comparable across sources. Distinct from speaker-match accuracy.
      - `votes` integer, nullable: For source 'ocr', the number of votes that produced the winning name. 0 for 'driver_selection'.
      - `samples` integer, nullable: For source 'ocr', the vote opportunities where this face was visible. Needed to tell confidence=1.0 from one vote apart from confidence=1.0 from thirty. 0 for 'driver_selection'.
      - `alternatives` object, nullable: For source 'ocr', other names read on screen and their vote counts. Empty for 'driver_selection'.
      - `is_local` boolean, nullable: For source 'ocr', true when the on-screen label read You/Me — that tile is the account holder. False for 'driver_selection'.
      - `source` 'ocr' | 'driver_selection', nullable: How the name was assigned: 'ocr' (read from an on-screen label) or 'driver_selection' (the in-vehicle role label "Driver" on the selected driver's face). A role label is not a person's name.
      - `inferred_from_prefix` boolean, nullable: For source 'ocr', true when every winning vote came from a truncated label whose prefix uniquely matched a full name read on some other face. The precision-first UI should treat this as a low-trust name. False for 'driver_selection'.
      - `reason` 'clear_lead' | 'sole_candidate', nullable: Why the role label was assigned: 'clear_lead' (one candidate clearly led) or 'sole_candidate' (only one candidate). Set only with source 'driver_selection'.
  - `annotated_video_mp4` unknown
  - `summary` string
  - `total_frames_count` integer, nullable
  - `fps` number, nullable
  - `height` number, nullable
  - `width` number, nullable
  - `status` string, required
  - `created_at` string
  - `thumbnail_image` string
  - `text_id` string

## Other responses

- `401`: Missing, malformed or rejected credentials — no `X-API-Key` / `Authorization: Bearer <jwt>`, an expired token, or a caller that lacks the role the route requires. Note that this API answers *authorization* failures with 401 as well as 403 (see the 403 entry where a route declares both).
- `404`: No such resource, or it is not visible to this caller. Ownership failures are reported as 404 rather than 403 so the API does not confirm the existence of another account's records.
- `422`: Validation Error

## Changes

- **2026-10-01** `72330e2229c7`: 1 breaking, 2 warning, 1 info
  - the `` response property const value `ocr` was removed for the status `200`
  - added the new `driver_selection` enum value to the `faces/anyOf[subschema #1: ListOfFaces]/faces/items/source/anyOf[subschema #1]/` response property for the response status `200`
  - added the new `ocr` enum value to the `faces/anyOf[subschema #1: ListOfFaces]/faces/items/source/anyOf[subschema #1]/` response property for the response status `200`
  - added the optional property `faces/anyOf[subschema #1: ListOfFaces]/faces/items/reason` to the response with the `200` status
- **2026-09-22** `536bf48bb9fb`: 3 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `OAuth2Delegated` was added to the API
- **2026-08-28** `3c1aeed97c95`: 7 info
  - added the optional property `faces/anyOf[subschema #1: ListOfFaces]/faces/items/alternatives` to the response with the `200` status
  - added the optional property `faces/anyOf[subschema #1: ListOfFaces]/faces/items/confidence` to the response with the `200` status
  - added the optional property `faces/anyOf[subschema #1: ListOfFaces]/faces/items/inferred_from_prefix` to the response with the `200` status
  - added the optional property `faces/anyOf[subschema #1: ListOfFaces]/faces/items/is_local` to the response with the `200` status
  - …3 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v1/videos/:video_id/get.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)