---
title: "Get Video Face Image Url Route"
method: GET
path: "/v2/videos/{video_id}/faces/{face_id}/image-url"
tags: ["Video Emotion API"]
---

# Get Video Face Image Url Route

`GET /v2/videos/{video_id}/faces/{face_id}/image-url`

## 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}/faces/{face_id}/image-url`
- 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 short-lived URL for a face's image.

The returned `url` serves the stored image of one detected face, ready to use as an
image source. It is short-lived: request a new one when `expires_at` passes or when a
request made with it is refused, and do not store or share it. A face's `image` field
in the video details is a stored reference, not guaranteed to be readable; this
endpoint is how to show it.

**Access Control:** the same as the video details. The owner and admins can always get
a face image URL. While a video is shared, or is a sample, anyone can, so sharing a
video lets anyone with its link see its faces.

**Errors:**
- **401**: not authorized to access this video
- **404**: video or face not found
- **409** `media_not_stored`: the face has no stored image (for example, a face added
  manually, or one whose image is not ready yet), or its image could not be looked up
  just now; retrying may succeed
- **503** `media_storage_unavailable`: the URL could not be issued; try again shortly

## Path parameters

- `video_id` string, required: The unique ID of the video.
- `face_id` integer, required: The ID of the face within the video.

## Response `200`

Successful Response

- FaceImageUrlResponse: A short-lived, read-only URL for one face's image.
  - `url` string, required: Signed URL of the face image, for use as an image source. Short-lived: request a new one when `expires_at` passes or a request with it is refused. Do not store or share it.
  - `expires_at` string, required: RFC 3339 UTC instant at which `url` stops working, e.g. `2026-09-28T12:30:00Z`.
  - `content_type` string, required: The image's content type, e.g. `image/jpeg`.

## 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.
- `409`: `media_not_stored`: this face has no stored image yet, or its image could not be looked up just now. Retrying may succeed.
- `422`: Validation Error
- `503`: `media_storage_unavailable`: try again shortly.

## Changes

- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

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