Skip to main content

Trigger Speaker Face Match

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

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​

{
  "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.

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

Request​

Responses​

Successful Response