---
title: "Get Speaker Face Match Suggestions Route"
method: GET
path: "/v2/videos/{video_id}/speaker-face-match/suggestions"
tags: ["Video Emotion API"]
---

# Get Speaker Face Match Suggestions Route

`GET /v2/videos/{video_id}/speaker-face-match/suggestions`

## 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}/speaker-face-match/suggestions`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Return the stored speaker-face match suggestions for a video.

One item per in-scope speaker when eligible speakers were matched. Unresolved speakers have `face_id` and
`accuracy` null and a `reasoning` explaining why. Never includes the
internal `match_evidence` dict.

404 when no suggestions block exists (no run yet, in-flight after a
trigger cleared the previous block, or after face/speaker add/delete/merge
invalidation). A completed run that resolved nothing still 200s with
all-null rows. If the requested scope has no eligible speakers, returns `items: []`
instead, with `reason: "no_speakers"` when the whole audio has no eligible speakers.
A timed-out run can still have no block; use the statuses terminal flag to stop polling.

Auth matches the trigger POST: owner or admin only.

## Error Responses

- **401 Unauthorized**: User is not authenticated or not authorized to access this video
- **404 Not Found**: Video not found, or no suggestions block is stored

## Path parameters

- `video_id` string, required: Unique identifier of the video.

## Response `200`

Successful Response

- SpeakerFaceMatchSuggestionsResponse: Stored suggestions block for ``GET .../speaker-face-match/suggestions``.
  - `reason` 'no_speakers', nullable: Completed audio has no eligible speakers; items is empty.
  - `generated_at` string, nullable
  - `target_speaker_ids` integer[], nullable
  - `items` SpeakerFaceMatchSuggestionItem[], required
    - `speaker_id` integer, required
    - `face_id` integer, nullable
    - `accuracy` number, nullable
    - `reasoning` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-06** `bc15cec7e794`: 1 info
  - added the optional property `reason` to the response with the `200` status
- **2026-09-08** `b10651168511`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/speaker-face-match/suggestions/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/9c4d258def38?raw)