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

# Trigger Speaker Face Match Suggestions

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

Trigger automatic speaker-to-face matching in **suggestions** mode.

Same body, auth, and prerequisites as `POST .../speaker-face-match`, but
does **not** write `face.speaker_id`, `face.accuracy`, or
`face.personality_traits`. The worker (or a fully-resolved name-channel
pre-pass) stores an advisory block on `video.speaker_face_match.suggestions`
that the client commits verbatim through the existing PUT.

Poll `GET .../statuses?speaker_face_match_status=true`. The stored in-flight
value is `"queue"` (the trigger **response** `status` is `"processing"`);
a finished suggest run writes `"completed"` or `"failed"`. `GET
.../speaker-face-match/suggestions` returns 404 when no block exists. Stop polling
when the statuses `states.speaker_face_match_status.terminal` flag is true, including
`failed` with `speaker_face_match_reason: "timed_out"`.

No eligible speakers in the requested scope completes immediately with `items: []`
and leaves bindings and personality unchanged. `reason: "no_speakers"` is included
only when the whole audio has no eligible speakers. Pending transcript replacement returns 409.

Returns **409** if a non-stale run is already in flight (`status=="queue"`
and `queued_at` within 15 minutes). `queued_at` is stamped only on
suggest-mode triggers. A historical or commit-mode `"queue"` with no
`queued_at` (commit-mode write-back never terminals that field) is treated
as stale and does not 409.

A commit-mode POST issued while a suggest run is in flight also 409s, so
an impatient click cannot convert the in-flight preview into a personality-
wiping commit. After the stale window that 409 lifts, a late suggest-era
worker `PUT .../matched_speakers` can still arrive. If a commit POST has
already cleared `mode` (and possibly personality), that late PUT takes
the **commit** branch and mutates `faces[]` with the old preview's matches.
There is no run-id on the worker contract to ignore it.

## Error Responses

- **401 Unauthorized**: User is not authenticated or not authorized to access this video
- **404 Not Found**: Video not found
- **409 Conflict**: Video or audio processing not completed, or a match run is already in flight
- **400 Bad Request**: Audio ID missing in video document, `target_speaker_ids` is an
  empty list, or `target_speaker_ids` contains a speaker ID not present in the audio
- **422 Unprocessable Entity**: Request body includes the removed `target_face_ids` field

## Path parameters

- `video_id` string, required: Unique identifier of the video. Video must be in 'completed' status with associated audio.

## Request body

- AutoSpeakerFaceMatchTriggerRequest: Request body for triggering the automatic speaker-face match worker. Attributes: target_speaker_ids (Optional[List[int]]): When omitted (or ``null``), behavior is byte-identical to today: every speaker is cleared and eligible for re-derivation. When provided (must be non-empty), only the listed speakers are cleared/re-derived; every other speaker's bound face is left untouched, and no target speaker's resolved match can steal a face currently held by a non-target ("protected") speaker. A speaker with no bound face can be targeted — that's the whole point (#1344): it can now be reached even though it has no face_id to key off of.
  - `target_speaker_ids` integer[], nullable

## Response `200`

Successful Response

- AutoSpeakerFaceMatchTriggerResponse: Response model for triggering the automatic speaker-face match worker. Attributes: video_id (str): Unique identifier of the video. audio_id (str): Unique identifier of the audio document. status (str): Status of the trigger operation (e.g., "processing"). message (str): Informational message about the operation.
  - `reason` 'no_speakers', nullable: Completed audio has no eligible speakers; no matching was needed.
  - `video_id` string, required
  - `audio_id` string, required
  - `status` string, required
  - `message` 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/post.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)