Skip to main content

Trigger Speaker Name Inference Route

POST 
/v2/audios/{audio_id}/speaker-name-inference

Trigger a manual, credit-billed, speaker-scoped re-run of transcript-based speaker-name inference for an audio.

The name signal itself is face-independent: a quote-grounded model pass over the diarized transcript that proposes a name per targeted speaker from self-intros ("Hi, I'm Mark") or third-person mentions ("Thanks, Priya"), each verified deterministically against the real transcript text before being persisted onto the speaker row and transcript sentences. For audio that belongs to a completed video, a face already matched to that speaker_id is updated only when it does not already carry an OCR-derived name. Interactive rename and a suggestion commit via PUT /v1/audios/{audio_id}/speakers/names may overwrite an OCR-derived face name; this persist path does not.

This endpoint mirrors the automatic, free, one-shot webhook hook, but without either of its restrictions: it does not require the audio to be freshly unnamed (targeting an already-named speaker is a legitimate, billed re-run — e.g. the name was wrong, or wiped), and it never touches a speaker outside target_speaker_ids, named or not.

This call is synchronous: it runs in-request (bounded by an internal timeout) and returns the final result rather than a processing/queued status, unlike speaker-face-match. A caller must be prepared to hold the connection open for the duration of the model call.

Request Body (required)​

  • target_speaker_ids: required, non-empty list of speaker ids to (re-)name. Every speaker not in this list is left byte-for-byte untouched, even if the model's transcript reasoning would otherwise have proposed something for them.
  • infer_roles: optional, default false. When true, the same model pass also proposes agent or customer per targeted speaker, grounded in a quote from that speaker's own words. Independent of the name verdict. Roles are never written; commit them via PUT /v1/audios/{audio_id}/speakers/roles. Targeting a speaker for a role also targets them for a rename; callers who want a role proposal without a possible rename should use .../speaker-name-inference/suggestions. A speaker whose stored role is already agent or customer is not offered a new role (role_already_set); clear the role and re-run to get a fresh proposal. Omitted and false are the same request.

Prerequisites​

  • User must be the audio owner or hold MEDIA_WRITE
  • Audio must be in 'completed' status. If the audio has a parent video, that video must also be completed (a paid name can otherwise be overwritten with Face {id} when speaker-face matching writes back)
  • The audio must be eligible for transcript-based name inference: not a meeting-platform ingest, no provider-supplied transcript/diarization, and no speech_segments pointer. A supplied or replaced transcript (PUT /v1/audios/{audio_id}/transcript/replace, or a URL+transcript upload) writes that pointer permanently, so Identify-people Suggest-names returns 400 for those items rather than running. The transcript itself must already be available
  • Caller must have a positive credit balance. This call is billed on success; the amount is not quoted here. A 402 is returned before the model runs when admission is refused

Response​

Returns at least one result row per requested target_speaker_id, each either an accepted rename (name, quote, pattern) or a rejection (reason) — including a row for any targeted speaker the model could not resolve. Duplicate model rows for the same id, if any, are not collapsed. When infer_roles is true, each row also carries an independent role verdict (role_accepted, and on accept role plus role_quote). Roles are not mutually exclusive across speakers. video_id is set when this audio has a parent video; it is null for audio-only media.

Error Responses​

  • 401 Unauthorized: User is not authenticated or not authorized to access this audio
  • 404 Not Found: Audio not found
  • 409 Conflict: Audio processing not completed, or parent video not completed
  • 400 Bad Request: Transcript not ready, target_speaker_ids is empty, contains a speaker ID not present in the audio or naming a synthetic track, the audio (or its parent video) is not eligible for this feature, or video_id points at a missing video
  • 402 Payment Required: Admission refused. Detail is the admission refusal_message. The wording differs for a zero vs. negative balance vs. a window refusal (buying credits does not fix the latter)
  • 422 Unprocessable Entity: target_speaker_ids is missing/null, or contains a non-integer entry; or infer_roles is null or not a boolean
  • 502 Bad Gateway: The model call failed or returned an unparseable response. No charge is applied

Request​

Responses​

Successful Response