---
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`

## 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/v2/videos/{video_id}/face_analysis`
- 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`

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.
    - `head_yaw` number, nullable: Head yaw in degrees. 0 = facing the camera; negative = turned left.
    - `head_pitch` number, nullable: Head pitch in degrees. Negative = head down. What 0 means depends on where the camera sits, so judge it against the same person's usual, not an absolute angle.
    - `head_roll` number, nullable: Head roll (tilt toward a shoulder) in degrees.
    - `brow_eye_ratio` number, nullable: Brow-to-eye distance over the inter-ocular distance (a proxy for brow lowering). Lower = a lowered brow. Absent when the face is too small or turned too far.
    - `brow_furrow_ratio` number, nullable: Distance between the inner brow points over the inter-ocular distance. Lower = more furrowed. Absent under the same conditions as brow_eye_ratio.
    - `brow_source` string, nullable: Landmark model the brow ratios were measured with. Ratios from different sources are not comparable.
    - `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

## Changes

- **2026-10-31** `bd825cd86e8c`: 6 info
  - added the optional property `frames/items/brow_eye_ratio` to the response with the `200` status
  - added the optional property `frames/items/brow_furrow_ratio` to the response with the `200` status
  - added the optional property `frames/items/brow_source` to the response with the `200` status
  - added the optional property `frames/items/head_pitch` to the response with the `200` status
  - …2 more
- **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-20** `74ceee4a5c98`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/face_analysis/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)