Skip to main content

Trigger Speaker Face Match Suggestions

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

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 404s while a run is in flight.

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

Request​

Responses​

Successful Response