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

# Get Multiple Frame

`GET /v1/videos/{video_id}/frames`

API to Retrieve Frames of the video based on video_id.

## Path parameters

- `video_id` string, required — The unique video ID of the video for which the frames to be fetched

## Query parameters

- `start_frame` string, nullable — The frame number from which retrieval should begin. Defaults to the start of the video if not provided.
- `length` string, nullable — The number of frames to retrieve, starting from 'start_frame'. If omitted, all available frames will be returned.
- `face_ids` string — Optional comma-separated list of face IDs (e.g., '1,2,3')

## Response `200`

Successful Response

- MultipleFramesResponse — Model for returning the MultipleFrame Responses
  - `processed_frames` FramesResponse[], required
    - `original_frame_image` string, nullable
    - `frame_image` string, nullable
    - `found_faces` integer[], nullable
    - `timestamp` integer, nullable
    - `faces` BoundingBox[], nullable
      - `face_id` integer, required
      - `box` integer[], required
      - `emotions` object, required
      - `note` string, nullable
      - `face_analysis` FaceAnalysis — Per-face gaze / eye / lip / liveness signals from temporal analysis. Every named field is optional: the producer omits what it could not compute, and a face that never went through temporal analysis carries no ``face_analysis`` key at all. Blink rate and the eye-tracking heatmap are not stored — derive rate from ``blink`` onsets over time, and the heatmap from ``gaze_yaw`` × ``gaze_pitch``.
        - `gaze_yaw` number, nullable — Horizontal gaze in degrees. 0 = camera; negative = left; positive = right.
        - `gaze_pitch` number, nullable — Vertical gaze in degrees. 0 = level; negative = down; positive = up.
        - `eye_openness` number, nullable — Eye openness in [0, 1].
        - `blink` boolean, nullable — True when the eyes are closed on this frame.
        - `fixation_id` integer, nullable — Fixation identifier; the same id spans consecutive frames of one fixation.
        - `liveness` string, nullable — Liveness label, e.g. 'live'.
        - `lip_openness` number, nullable — Mouth aspect ratio / lip openness in [0, 1].
        - `lip_state` string, nullable — Lip state: idle, speaking, or yawning.
    - `frame_id` integer, nullable
    - `note` string, nullable

## 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/74ceee4a5c98/schema)