---
title: "Get Video Face Analysis"
method: GET
path: "/v2/videos/{video_id}/face_analysis"
tags: ["Video Emotion API"]
---

# Get Video Face Analysis

`GET /v2/videos/{video_id}/face_analysis`

Per-frame gaze, eye, blink, liveness, and lip signals — no frame images.

Same authorization as other video GETs (owner, admin, shared, or sample).

Each `frames[]` row is one face on one frame. Fields the pipeline did not
compute are omitted.

Blink rate is not returned. Count `False`→`True` transitions on `blink`
and divide by the face's duration in minutes. The eye-tracking heatmap is
not a stored dataset — it is a density view of `gaze_yaw` × `gaze_pitch`.

Page with `start_frame` + `length` on long videos. `length=0` (default) pulls
every frame from frames-service, same as `GET /v1/videos/{id}/frames`.

## Path parameters

- `video_id` string, required — The unique video ID of the video to fetch face analysis from

## Query parameters

- `face_id` integer, nullable — Optional face ID to restrict the series to one face
- `start_frame` integer — First frame number to include (inclusive). Ignored when length is 0.
- `length` integer — Max frames to fetch by frame number. 0 = the whole video. Prefer a bound on long videos.

## Response `200`

Successful Response

- VideoFaceAnalysisResponse — Image-free gaze / eye / lip time-series for a processed video.
  - `video_id` string, required
  - `frames` FaceAnalysisRow[], required
    - `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 — Frame number.
    - `timestamp` integer, nullable — Frame timestamp in milliseconds.
    - `face_id` integer, nullable — Detected face identifier.

## 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)