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

# Trigger Speaker Face Match

`POST /v2/videos/{video_id}/speaker-face-match`

## 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`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Trigger automatic AI-driven speaker-to-face matching for a video.

This endpoint first runs a deterministic name-channel pre-pass that joins
face names (typically OCR-read face-tile names, but any real name already
present on an unmatched face) against provider speaker names (exact,
fuzzy, and truncated-prefix tiers). If every **non-synthetic** speaker
(screen-share/system tracks excluded) ends up decisively linked, the match
is marked complete immediately and the lip-sync worker is skipped. A
generic diarization label (e.g. `"Speaker 3"`) still counts as a
non-synthetic speaker that must be linked — the pre-pass cannot name-link
it, so it forces the worker path. Otherwise, any decisive links found are
applied and this endpoint falls back to the asynchronous AI worker as
before, which may still refine or overwrite them.

## Request Body (optional)

- `target_speaker_ids`: when omitted (or the request has no body at all),
  behavior is unchanged — every speaker is cleared and eligible for
  re-derivation, exactly as before this parameter existed. When provided
  as a non-empty list of speaker IDs, only those speakers are cleared and
  re-derived; every other speaker's bound face is left untouched, and no
  face currently held by a non-target ("protected") speaker can be stolen
  by a target speaker's resolved match — that guarantee holds for both
  this endpoint's synchronous pre-pass and the asynchronous worker's
  later callback. A speaker with no bound face can be targeted.

## Prerequisites

- User must be the video owner or an admin
- Video must be in 'completed' status
- Audio must be in 'completed' status
- Video must have an associated audio_id

## Response

```json
{
  "video_id": "abc123",
  "audio_id": "xyz789",
  "status": "processing",
  "message": "Speaker-face match worker triggered successfully"
}
```

`status` is `"completed"` instead of `"processing"` when the name-channel
pre-pass alone resolved every non-synthetic speaker (or, for a scoped
request, every targeted speaker) and the worker was skipped.

Completed audio with no eligible speakers returns `completed` and `reason: "no_speakers"`
immediately, leaving bindings and personality unchanged. A synthetic-only requested scope
also completes immediately; the reason is omitted if other eligible speakers exist.
Pending transcript replacement returns 409.

## 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 suggestions run is 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
  - added optional request body

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