Skip to content

feat(diarization): add the Diarization API client - #306

Draft
mez171 wants to merge 1 commit into
masterfrom
mez/diarization-api
Draft

mez171 wants to merge 1 commit into
masterfrom
mez/diarization-api

Conversation

@mez171

@mez171 mez171 commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Adds a client for the standalone Diarization API (POST /v1/diarize), which labels the speakers in an audio file.

What's added

  • aai.Diarizer and aai.AsyncDiarizer with diarize(audio, transcript=None, config=None, *, content_type=None). They follow the layout of the TTS and Dictation clients.
  • Two ways to call it:
    • With a transcript: pass a SyncTranscriptResponse (requested with timestamps=True), a dict with words, or a list of words. Each word comes back with a speaker and the words are grouped into utterances.
    • Audio only: omit transcript to get speaker turns (segments) and speakers. Diarization can then run in parallel with transcription.
  • Models: DiarizationConfig (sample_rate, channels, language_code; unknown fields are rejected) and DiarizationResponse (words, utterances, segments, speakers, audio_duration_ms, session_id, request_time_ms).
  • DiarizationError is built by the existing problem+json mapper (sync/v1/api.py::_error_from_response). It carries status_code, error_code and retry_after.
  • Settings:
    • diarization_base_url defaults to https://diarization.assemblyai.com. Set it to https://diarization.us.assemblyai.com or https://diarization.eu.assemblyai.com to keep requests in that data zone.
    • diarization_http_timeout defaults to 330 s: the server's 300 s inference timeout plus its 10 s queue wait, with margin.
  • Content type comes from the file extension, using Dictation's map. Setting sample_rate/channels sends audio/pcm. content_type= overrides both. The body is a buffered multipart upload so Content-Length is always set; the API returns 411 without it.
  • Docs:
    • a README section;
    • CLAUDE.md entries;
    • the API reference build and check scripts.
  • Version: 1.10.12 → 1.11.0, a minor bump for a new product, as feat(tts): Text-to-Speech HTTP client #277 did.

Testing

  • pytest -n auto -q: 1076 passed, 42 of them new (tests/unit/test_diarization.py, test_diarization_async.py). The new tests cover:
    • both modes and an empty word list;
    • a transcript passed as a sync response object or as a list of words;
    • the PCM config, extension inference and the override;
    • URL rejection;
    • problem+json errors (400/401/411/413/415/503 with Retry-After/504) and a non-JSON 502;
    • the custom base URL, the timeout and api_key=.
  • tox py311-latest, py312-latest, py311-httpx0.22, py311-httpx0.24, py311-pydantic1.10 and py311-websockets11.0 all pass. The legacy envs caught two real bugs, both fixed:
    • httpx 0.22 rejects str multipart parts;
    • pydantic 1.10 was misdetected as v2.
  • ruff format --check and ruff check pass, and check_api_docs.py reports "API reference OK".
  • None of the tests call the real API.

Notes for review

  • Names: Diarizer / AsyncDiarizer / Diarization*. Happy to rename to match house style.
  • Dict transcript: a dict is sent as is, so pass t or t.words rather than {"words": t.words}.
  • Content-type map: imported from dictation.v1._base, the same pattern as Dictation importing the sync error parser.

The API itself is live in us-west-2 and eu-west-1. Docs: AssemblyAI/assemblyai-docs#584 (in review; its samples will use this client).

🤖 Generated with Claude Code

Add aai.Diarizer and aai.AsyncDiarizer for POST /v1/diarize on
diarization.assemblyai.com (US/EU data-residency hosts via
settings.diarization_base_url). diarize(audio, transcript=None,
config=None, *, content_type=None) posts a buffered multipart body
(Content-Length is required by the API) with the audio, an optional
JSON transcript (a SyncTranscriptResponse, a dict with words, or a
list of words) and an optional DiarizationConfig. Omitting the
transcript runs segments-only mode.

The audio Content-Type is inferred from the extension (shared with
Dictation), audio/pcm when sample_rate/channels are set, and can be
overridden. problem+json errors map to DiarizationError through the
sync API's shared parser. Bumps the version to 1.11.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mez171
mez171 requested a review from ccampbell-aai November 19, 2026 17:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant