diff --git a/CLAUDE.md b/CLAUDE.md
index f739d6f..e4656dc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -59,6 +59,11 @@ aai.settings.api_key = "your-key"
- `aai.TTSConfig` — Text-to-Speech options: `voice_id` (a library voice such as `aai-jane`, or a cloned voice by UUID or slug), `model_id` (`assemblyai-tts-1`), `language`, `sample_rate`, `encoding` (`aai.TTSEncoding`: `pcm_s16le` default | `pcm_mulaw` | `pcm_alaw` | `mp3`), `container` (`aai.TTSContainer`: `raw` default | `wav`), `bit_rate`, `extend_biometric_consent` (owner-only consent renewal of a cloned voice). Rejects unknown fields
- `aai.TTSResponse` — Text-to-Speech result: `.audio` (bytes) plus the response headers: `.request_id`, `.region`, `.model`, `.voice_id`, `.language`, `.encoding`, `.sample_rate`, `.container`, `.bit_rate`, `.content_type`, `.voice_expires_at`, `.billed_characters`, `.audio_duration_ms`. `TTSStream.info` carries the same fields without `audio`; `audio_duration_ms` is `None` on a stream with audio (`0` when the text had nothing to speak)
- `aai.TTSError` — Raised on any Text-to-Speech refusal: `.status_code`, `.error_code` (stable API code; `biometric_terms_not_accepted` 403 until the account accepts the biometric data terms in the dashboard, `auth_unavailable` 503 retryable; on a session these arrive as close 3006 and 1011, with `status_code` None, the close code in `.body["close_code"]` and `.retryable` from the API's Error frame), `.param`, `.request_id`, `.retryable`, `.retry_after`, `.errors`, `.body` (the whole envelope)
+- `aai.Diarizer` — Diarization API: speaker labels for one audio file per request. `diarize(audio, transcript=None, config=None, *, content_type=None)`: `audio` is a path, bytes or binary file object; `transcript` is a `SyncTranscriptResponse` (request it with `timestamps=True`), a dict with `words`, or a list of words (`text`, `start`/`end` ms, optional `confidence`). Omit `transcript` for segments-only mode (`words`/`utterances` empty). Content-Type from the extension (`audio/wav` default, `audio/pcm` when `sample_rate`/`channels` set, `audio/mpeg`, `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`) unless `content_type=` is given. Host from `aai.settings.diarization_base_url` (`https://diarization.assemblyai.com`; `https://diarization.us.assemblyai.com` / `https://diarization.eu.assemblyai.com` for data residency)
+- `aai.AsyncDiarizer` — Asyncio counterpart of `Diarizer`; `diarize()` is a coroutine. Owns an HTTP pool: use `async with` or `await aclose()`
+- `aai.DiarizationConfig` — Diarization options: `sample_rate`, `channels` (raw PCM only), `language_code` (default `en`). Rejects unknown fields
+- `aai.DiarizationResponse` — Diarization result: `.words` (`DiarizedWord`: `text`, `start`, `end`, `confidence`, `speaker`, `speaker_confidence`), `.utterances` (`DiarizationUtterance`: `speaker`, `text`, `start`, `end`, `confidence`, `speaker_confidence`, `words`), `.segments` (`DiarizationSegment`: `start`, `end`, `speaker`, `speaker_confidence`), `.speakers`, `.audio_duration_ms`, `.session_id`, `.request_time_ms`
+- `aai.DiarizationError` — Raised on any Diarization API refusal: `.status_code` (401 bad key, 400 validation, 411/413/415, 5xx), `.error_code` (snake_cased problem title, e.g. `unauthorized`, `bad_request`), `.retry_after`
- `assemblyai.streaming.v3.RealTimeTranscriber` — Real-time streaming with event-based API (threaded)
- `assemblyai.streaming.v3.AsyncRealTimeTranscriber` — Asyncio-native counterpart; same options/events
- `aai.LLMGateway` — LLM Gateway client. Resources: `models.list()`, `chat.completions.create()` (incl. `stream=True`), `understanding.create()`/`.validate()`, `decisions.create()`
diff --git a/README.md b/README.md
index 105d5c5..04d55b2 100644
--- a/README.md
+++ b/README.md
@@ -1098,6 +1098,81 @@ print(response.voice_expires_at) # Unix seconds
+### **Diarization Examples**
+
+`aai.Diarizer` labels the speakers in an audio file with one request to the Diarization API (`POST /v1/diarize`). Pass the audio with its transcript to get each word's speaker and the utterances; leave the transcript out to get only the speaker turns, so diarization can run alongside transcription instead of after it. Speakers are labelled `A`, `B`, and so on, up to 8.
+
+The audio is a local path, bytes or a binary file object (not a URL). Its Content-Type, which picks the decoder, comes from the file extension: `audio/wav`, `audio/mpeg`, `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`, or `audio/pcm` for `.pcm`/`.raw` and whenever `sample_rate`/`channels` are set on the `DiarizationConfig`. Audio with no known extension is sent as WAV; pass `content_type=` to set it yourself. `DiarizationConfig` takes `sample_rate` and `channels` (raw PCM only) and `language_code` (default `en`), and rejects unknown fields.
+
+Requests go to `aai.settings.diarization_base_url`, `https://diarization.assemblyai.com` by default; set it to `https://diarization.us.assemblyai.com` or `https://diarization.eu.assemblyai.com` to keep them in the US or EU data zone.
+
+
+ Label the words of a sync transcript
+
+```python
+import assemblyai as aai
+
+aai.settings.api_key = ""
+
+# Word timestamps are needed to place each word: request them.
+transcript = aai.SyncTranscriber().transcribe(
+ "./call.wav", config=aai.SyncTranscriptionConfig(timestamps=True)
+)
+
+result = aai.Diarizer().diarize("./call.wav", transcript=transcript)
+
+for utterance in result.utterances:
+ print(f"Speaker {utterance.speaker}: {utterance.text}")
+
+for word in result.words:
+ print(word.text, word.start, word.end, word.speaker, word.speaker_confidence)
+```
+
+`transcript` also takes a dict with a `words` list, or the list of words alone, each with `text`, `start` and `end` in milliseconds and an optional `confidence`; other fields are ignored. A word without timings gets them from the words next to it. An empty list returns empty results.
+
+
+
+
+ Speaker turns only (no transcript)
+
+```python
+result = aai.Diarizer().diarize(
+ pcm_bytes,
+ config=aai.DiarizationConfig(sample_rate=16000, channels=1),
+)
+
+print(result.speakers) # ["A", "B"]
+for segment in result.segments:
+ print(segment.speaker, segment.start, segment.end, segment.speaker_confidence)
+```
+
+Without a transcript, `words` and `utterances` are empty and `segments` and `speakers` are filled.
+
+
+
+
+ Asyncio and errors
+
+```python
+import asyncio
+import assemblyai as aai
+
+async def main():
+ async with aai.AsyncDiarizer() as diarizer:
+ try:
+ result = await diarizer.diarize("./call.mp3")
+ except aai.DiarizationError as error:
+ print(error.status_code, error.error_code, error)
+ return
+ print(result.speakers, result.audio_duration_ms)
+
+asyncio.run(main())
+```
+
+`aai.AsyncDiarizer` owns an HTTP pool: use `async with` or `await aclose()`, or pass an `aai.AsyncClient` to share one. Refusals raise `aai.DiarizationError` with the HTTP `status_code`, the snake_cased problem `title` as `error_code` (`unauthorized` for a missing or invalid key, `bad_request` for an unknown config field or a transcript without `words`, `audio_too_large`, `unsupported_media_type`, `capacity_exceeded`, `inference_timeout`), and `retry_after` when the API sends `Retry-After`. Requests wait up to `aai.settings.diarization_http_timeout` (330 s by default).
+
+
+
### **Asyncio Examples**
`aai.AsyncTranscriber` is the asyncio counterpart of `aai.Transcriber`. Every method
@@ -2224,6 +2299,7 @@ All custom SDK exceptions inherit from `aai.AssemblyAIError`, except the streami
| `aai.TranscriptError` | Raised when a prerecorded transcript API call fails at the HTTP level or polling times out. | `status_code: Optional[int]` |
| `aai.SyncTranscriptError` | Raised when synchronous transcription fails (`aai.SyncTranscriber`). | `status_code: Optional[int]`, `error_code: Optional[str]`, `retry_after: Optional[int]` |
| `aai.TTSError` | Raised when a Text-to-Speech request fails (`aai.TextToSpeech`) or a session is refused or fails (`aai.TTSSession`, where `status_code` is `None`, `request_id` is the session id and `body["close_code"]` is the WebSocket close code). | `status_code: Optional[int]`, `error_code: Optional[str]`, `param: Optional[str]`, `request_id: Optional[str]`, `retryable: Optional[bool]`, `retry_after: Optional[int]`, `errors: Optional[List[Dict[str, Optional[str]]]]`, `body: Optional[dict]` |
+| `aai.DiarizationError` | Raised when a Diarization API request fails (`aai.Diarizer`, `aai.AsyncDiarizer`). | `status_code: Optional[int]`, `error_code: Optional[str]`, `retry_after: Optional[int]` |
| `assemblyai.types.RedactedAudioIncompleteError` | Raised when requesting redacted audio before processing completes. | `status_code: Optional[int]` |
| `assemblyai.types.RedactedAudioExpiredError` | Raised when requesting redacted audio that has expired and is no longer available. | `status_code: Optional[int]` |
| `assemblyai.types.RedactedAudioUnavailableError` | Raised when requesting redacted audio that is unavailable at the given URL. | `status_code: Optional[int]` |
diff --git a/assemblyai/__init__.py b/assemblyai/__init__.py
index d36a862..b536e06 100644
--- a/assemblyai/__init__.py
+++ b/assemblyai/__init__.py
@@ -1,6 +1,16 @@
from .__version__ import __version__
from .async_client import AsyncClient
from .client import Client
+from .diarization.v1 import (
+ AsyncDiarizer,
+ DiarizationConfig,
+ DiarizationError,
+ DiarizationResponse,
+ DiarizationSegment,
+ DiarizationUtterance,
+ DiarizedWord,
+ Diarizer,
+)
from .dictation.v1 import (
AsyncDictationTranscriber,
DictationConfig,
@@ -156,6 +166,7 @@ def __getattr__(name: str):
"ActionItemsResponse",
"AssemblyAIError",
"AsyncClient",
+ "AsyncDiarizer",
"AsyncDictationTranscriber",
"AsyncLLMGateway",
"AsyncSyncTranscriber",
@@ -174,6 +185,13 @@ def __getattr__(name: str):
"ContentSafetySeverityScore",
"CustomFormattingRequest",
"CustomFormattingResponse",
+ "DiarizationConfig",
+ "DiarizationError",
+ "DiarizationResponse",
+ "DiarizationSegment",
+ "DiarizationUtterance",
+ "DiarizedWord",
+ "Diarizer",
"DictationConfig",
"DictationError",
"DictationResponse",
diff --git a/assemblyai/__version__.py b/assemblyai/__version__.py
index d6a282f..f84c53b 100644
--- a/assemblyai/__version__.py
+++ b/assemblyai/__version__.py
@@ -1 +1 @@
-__version__ = "1.10.12"
+__version__ = "1.11.0"
diff --git a/assemblyai/diarization/__init__.py b/assemblyai/diarization/__init__.py
new file mode 100644
index 0000000..36fbee0
--- /dev/null
+++ b/assemblyai/diarization/__init__.py
@@ -0,0 +1,31 @@
+"""The Diarization API: audio (and optionally its transcript) in, speaker labels out.
+
+The implementation lives in ``diarization/v1/``, mirroring the ``tts/v1/`` and
+``dictation/v1/`` layout. This ``__init__`` re-exports the public surface so
+``from assemblyai.diarization import Diarizer`` works alongside the versioned
+path.
+"""
+
+from .v1 import (
+ AsyncDiarizer,
+ DiarizationConfig,
+ DiarizationError,
+ DiarizationResponse,
+ DiarizationSegment,
+ DiarizationUtterance,
+ DiarizedWord,
+ Diarizer,
+ TranscriptInput,
+)
+
+__all__ = [
+ "AsyncDiarizer",
+ "DiarizationConfig",
+ "DiarizationError",
+ "DiarizationResponse",
+ "DiarizationSegment",
+ "DiarizationUtterance",
+ "DiarizedWord",
+ "Diarizer",
+ "TranscriptInput",
+]
diff --git a/assemblyai/diarization/v1/__init__.py b/assemblyai/diarization/v1/__init__.py
new file mode 100644
index 0000000..91d9dcd
--- /dev/null
+++ b/assemblyai/diarization/v1/__init__.py
@@ -0,0 +1,23 @@
+from ._base import TranscriptInput
+from .async_client import AsyncDiarizer
+from .client import Diarizer
+from .models import (
+ DiarizationConfig,
+ DiarizationError,
+ DiarizationResponse,
+ DiarizationSegment,
+ DiarizationUtterance,
+ DiarizedWord,
+)
+
+__all__ = [
+ "AsyncDiarizer",
+ "DiarizationConfig",
+ "DiarizationError",
+ "DiarizationResponse",
+ "DiarizationSegment",
+ "DiarizationUtterance",
+ "DiarizedWord",
+ "Diarizer",
+ "TranscriptInput",
+]
diff --git a/assemblyai/diarization/v1/_base.py b/assemblyai/diarization/v1/_base.py
new file mode 100644
index 0000000..df75cf7
--- /dev/null
+++ b/assemblyai/diarization/v1/_base.py
@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union
+
+from ... import _audio, types
+from ..._audio import AudioInput
+from ...dictation.v1._base import _CONTENT_TYPES
+from .models import DiarizationConfig
+
+__all__ = [
+ "AudioInput",
+ "TranscriptInput",
+ "check_config",
+ "resolve_request",
+]
+
+# A transcript to label: the sync API's response (request it with
+# `timestamps=True`), a dict with a `words` list, or the list of words alone.
+# Each word is a `SyncWord` or a dict with `text`, `start` and `end` in
+# milliseconds and an optional `confidence`; other fields are ignored.
+TranscriptInput = Union[
+ types.SyncTranscriptResponse,
+ Mapping[str, Any],
+ Sequence[Union[types.SyncWord, Mapping[str, Any]]],
+]
+
+
+def check_config(owner: str, config: Optional[DiarizationConfig]) -> None:
+ """Raises unless `config` is a `DiarizationConfig` or `None`."""
+
+ _audio.check_config(owner, config, DiarizationConfig)
+
+
+def _dump(model: Any) -> Any:
+ if hasattr(model, "model_dump"):
+ return model.model_dump(exclude_none=True)
+ if hasattr(model, "dict"):
+ return model.dict(exclude_none=True)
+ return model
+
+
+def _transcript_json(transcript: Optional[TranscriptInput]) -> Optional[Dict[str, Any]]:
+ """The JSON `transcript` part, or `None` to leave the part out."""
+
+ if transcript is None:
+ return None
+ if isinstance(transcript, Mapping):
+ return dict(transcript)
+ words: Any = getattr(transcript, "words", transcript)
+ if isinstance(words, (str, bytes, bytearray)) or not isinstance(words, Sequence):
+ raise TypeError(
+ "transcript must be a SyncTranscriptResponse, a dict with `words`, "
+ f"or a list of words, not {type(transcript).__name__}"
+ )
+ return {"words": [_dump(w) for w in words]}
+
+
+def resolve_request(
+ owner: str,
+ audio: AudioInput,
+ transcript: Optional[TranscriptInput],
+ config: Optional[DiarizationConfig],
+ content_type: Optional[str],
+) -> Tuple[bytes, str, str, Optional[dict], Optional[dict]]:
+ """
+ Reads the audio and builds the parts of a diarize request.
+
+ The audio's Content-Type comes from `content_type` when given, else from
+ the file extension (`.mp3` -> `audio/mpeg`, ...), else `audio/pcm` when
+ `sample_rate`/`channels` are set, else `audio/wav`.
+
+ Returns: `(audio_bytes, filename, content_type, transcript_json, config_json)`.
+ """
+
+ check_config(owner, config)
+ config = config or DiarizationConfig()
+ data, filename, inferred = _audio._resolve_audio(
+ audio,
+ sample_rate=config.sample_rate,
+ channels=config.channels,
+ owner=owner,
+ config_name="DiarizationConfig",
+ content_types=_CONTENT_TYPES,
+ )
+ return (
+ data,
+ filename,
+ content_type or inferred,
+ _transcript_json(transcript),
+ _audio._config_to_json(config),
+ )
diff --git a/assemblyai/diarization/v1/api.py b/assemblyai/diarization/v1/api.py
new file mode 100644
index 0000000..8a7bc64
--- /dev/null
+++ b/assemblyai/diarization/v1/api.py
@@ -0,0 +1,98 @@
+import json
+from typing import Any, List, Optional, Tuple
+
+import httpx
+
+from ... import types
+from ...sync.v1.api import _error_from_response as _shared_error_from_response
+from .models import DiarizationError, DiarizationResponse
+
+ENDPOINT_DIARIZE = "/v1/diarize"
+
+
+def _error_from_response(response: httpx.Response) -> types.AssemblyAIError:
+ """
+ Builds a `DiarizationError` from a non-200 response.
+
+ The Diarization API answers with the same RFC 9457 problem-details body
+ (`{"status", "title", "detail"}`) as the sync API, so the parsing is
+ shared and only the exception class differs.
+ """
+
+ return _shared_error_from_response(response, DiarizationError, "diarization")
+
+
+def _files(
+ *,
+ audio: bytes,
+ filename: str,
+ audio_content_type: str,
+ transcript: Optional[dict],
+ config: Optional[dict],
+) -> List[Tuple[str, Tuple[Optional[str], Any, str]]]:
+ """
+ The multipart parts of a diarize request.
+
+ Buffered, so httpx sends `Content-Length`, which the API requires (411).
+ An absent `transcript` leaves its part out: segments-only mode.
+ """
+
+ files: List[Tuple[str, Tuple[Optional[str], Any, str]]] = []
+ if config is not None:
+ files.append(
+ ("config", (None, json.dumps(config).encode(), "application/json"))
+ )
+ if transcript is not None:
+ files.append(
+ ("transcript", (None, json.dumps(transcript).encode(), "application/json"))
+ )
+ files.append(("audio", (filename, audio, audio_content_type)))
+ return files
+
+
+def _parse(response: httpx.Response) -> DiarizationResponse:
+ if response.status_code != httpx.codes.OK:
+ raise _error_from_response(response)
+
+ return DiarizationResponse.parse_obj(response.json())
+
+
+def diarize(
+ client: httpx.Client,
+ *,
+ base_url: str,
+ audio: bytes,
+ filename: str,
+ audio_content_type: str,
+ transcript: Optional[dict],
+ config: Optional[dict],
+ timeout: float,
+) -> DiarizationResponse:
+ """
+ Posts a diarize request.
+
+ Args:
+ client: the HTTP client (carries the `Authorization` header).
+ base_url: the Diarization API base URL, e.g. `https://diarization.assemblyai.com`.
+ audio: the audio bytes.
+ filename: name for the audio multipart part.
+ audio_content_type: the audio part's Content-Type; selects the decoder.
+ transcript: the JSON `transcript` part, or None to leave it out.
+ config: the JSON `config` part, or None to leave it out.
+ timeout: the httpx timeout in seconds.
+
+ Raises: `DiarizationError` on any non-200 response.
+ """
+
+ response = client.post(
+ base_url.rstrip("/") + ENDPOINT_DIARIZE,
+ files=_files(
+ audio=audio,
+ filename=filename,
+ audio_content_type=audio_content_type,
+ transcript=transcript,
+ config=config,
+ ),
+ timeout=timeout,
+ )
+ return _parse(response)
diff --git a/assemblyai/diarization/v1/async_api.py b/assemblyai/diarization/v1/async_api.py
new file mode 100644
index 0000000..7e00fe5
--- /dev/null
+++ b/assemblyai/diarization/v1/async_api.py
@@ -0,0 +1,37 @@
+"""The asyncio counterpart of `api.py`: same endpoint, parts and errors."""
+
+from typing import Optional
+
+import httpx
+
+from .api import ENDPOINT_DIARIZE, _files, _parse
+from .models import DiarizationResponse
+
+__all__ = ["diarize"]
+
+
+async def diarize(
+ client: httpx.AsyncClient,
+ *,
+ base_url: str,
+ audio: bytes,
+ filename: str,
+ audio_content_type: str,
+ transcript: Optional[dict],
+ config: Optional[dict],
+ timeout: float,
+) -> DiarizationResponse:
+ """Posts a diarize request. The asyncio counterpart of `api.diarize`."""
+
+ response = await client.post(
+ base_url.rstrip("/") + ENDPOINT_DIARIZE,
+ files=_files(
+ audio=audio,
+ filename=filename,
+ audio_content_type=audio_content_type,
+ transcript=transcript,
+ config=config,
+ ),
+ timeout=timeout,
+ )
+ return _parse(response)
diff --git a/assemblyai/diarization/v1/async_client.py b/assemblyai/diarization/v1/async_client.py
new file mode 100644
index 0000000..4d6380c
--- /dev/null
+++ b/assemblyai/diarization/v1/async_client.py
@@ -0,0 +1,139 @@
+import asyncio
+import functools
+from typing import Optional
+
+from ... import async_client as _async_client
+from . import async_api
+from ._base import AudioInput, TranscriptInput, check_config, resolve_request
+from .models import DiarizationConfig, DiarizationResponse
+
+__all__ = ["AsyncDiarizer"]
+
+
+class AsyncDiarizer:
+ """
+ Speaker labels for audio, for asyncio: the counterpart of `Diarizer`.
+
+ Same options, result and errors; `diarize()` is a coroutine, and a path
+ or file object is read on a worker thread. Owns an HTTP pool: use
+ `async with` or `await aclose()`, or pass an `aai.AsyncClient` to share
+ one.
+
+ Example:
+ ```python
+ import asyncio
+ import assemblyai as aai
+
+ aai.settings.api_key = "your-key"
+
+ async def main():
+ async with aai.AsyncDiarizer() as diarizer:
+ result = await diarizer.diarize("call.wav")
+ for segment in result.segments:
+ print(segment.speaker, segment.start, segment.end)
+
+ asyncio.run(main())
+ ```
+ """
+
+ def __init__(
+ self,
+ *,
+ client: Optional[_async_client.AsyncClient] = None,
+ config: Optional[DiarizationConfig] = None,
+ api_key: Optional[str] = None,
+ ) -> None:
+ """
+ Creates an `AsyncDiarizer`.
+
+ Args:
+ client: The `AsyncClient` to use. If `None`, one is created from
+ the global `settings` and closed on `aclose()`. Pass a client
+ to share one pool between instances.
+ config: Default options. A per-call `config` replaces it whole.
+ api_key: The API key to authenticate with. Builds and owns an
+ `AsyncClient` from it. Given alongside `client`, it takes
+ precedence and the given client is left untouched.
+
+ Raises:
+ TypeError: if `config` is not a `DiarizationConfig`.
+ """
+ check_config(type(self).__name__, config)
+
+ self._owns_client = client is None or api_key is not None
+ self._client = _async_client._resolve_client(client, api_key)
+ self.config = config or DiarizationConfig()
+
+ @property
+ def config(self) -> DiarizationConfig:
+ """The default configuration of the `AsyncDiarizer`."""
+ return self._config
+
+ @config.setter
+ def config(self, config: DiarizationConfig) -> None:
+ check_config(type(self).__name__, config)
+
+ self._config = config or DiarizationConfig()
+
+ @property
+ def client(self) -> _async_client.AsyncClient:
+ """The `AsyncClient` this instance sends requests with."""
+
+ return self._client
+
+ async def diarize(
+ self,
+ audio: AudioInput,
+ transcript: Optional[TranscriptInput] = None,
+ config: Optional[DiarizationConfig] = None,
+ *,
+ content_type: Optional[str] = None,
+ ) -> DiarizationResponse:
+ """
+ Labels the speakers in `audio`.
+
+ The asyncio counterpart of `Diarizer.diarize`; same arguments.
+
+ Raises:
+ DiarizationError: on any API refusal.
+ """
+ (
+ data,
+ filename,
+ audio_content_type,
+ transcript_json,
+ config_json,
+ ) = await asyncio.get_running_loop().run_in_executor(
+ None,
+ functools.partial(
+ resolve_request,
+ type(self).__name__,
+ audio,
+ transcript,
+ config or self._config,
+ content_type,
+ ),
+ )
+
+ return await async_api.diarize(
+ self._client.http_client,
+ base_url=self._client.settings.diarization_base_url,
+ audio=data,
+ filename=filename,
+ audio_content_type=audio_content_type,
+ transcript=transcript_json,
+ config=config_json,
+ timeout=self._client.settings.diarization_http_timeout,
+ )
+
+ async def aclose(self) -> None:
+ """Closes the HTTP pool this instance owns. A shared `client` is left open."""
+
+ if self._owns_client:
+ await self._client.aclose()
+
+ async def __aenter__(self) -> "AsyncDiarizer":
+ return self
+
+ async def __aexit__(self, *exc: object) -> None:
+ await self.aclose()
diff --git a/assemblyai/diarization/v1/client.py b/assemblyai/diarization/v1/client.py
new file mode 100644
index 0000000..bbbb437
--- /dev/null
+++ b/assemblyai/diarization/v1/client.py
@@ -0,0 +1,157 @@
+from typing import Optional
+
+from ... import client as _client
+from . import api
+from ._base import AudioInput, TranscriptInput, check_config, resolve_request
+from .models import DiarizationConfig, DiarizationResponse
+
+__all__ = ["Diarizer"]
+
+
+class Diarizer:
+ """
+ Speaker labels for audio: the Diarization API, one file per request.
+
+ Pass the audio with a transcript, such as a `SyncTranscriber` result
+ requested with `timestamps=True`, to get each word's speaker and the
+ utterances. Leave the transcript out to get only the speaker turns
+ (`segments`) and `speakers`, so diarization can run alongside
+ transcription instead of after it.
+
+ Requests go to `settings.diarization_base_url`,
+ `https://diarization.assemblyai.com` by default; set
+ `https://diarization.us.assemblyai.com` or
+ `https://diarization.eu.assemblyai.com` to keep them in the US or EU.
+
+ Example:
+ ```python
+ import assemblyai as aai
+
+ aai.settings.api_key = "your-key"
+
+ transcript = aai.SyncTranscriber().transcribe(
+ "call.wav", config=aai.SyncTranscriptionConfig(timestamps=True)
+ )
+ result = aai.Diarizer().diarize("call.wav", transcript=transcript)
+ for utterance in result.utterances:
+ print(f"{utterance.speaker}: {utterance.text}")
+ ```
+ """
+
+ def __init__(
+ self,
+ *,
+ client: Optional[_client.Client] = None,
+ config: Optional[DiarizationConfig] = None,
+ api_key: Optional[str] = None,
+ ) -> None:
+ """
+ Creates a `Diarizer`.
+
+ Args:
+ client: The HTTP client to use. Defaults to the shared default
+ client. A client you pass stays yours to close.
+ config: Default options. A per-call `config` replaces it whole.
+ api_key: The API key to authenticate with. Builds a `Client` for
+ this instance. Given alongside `client`, it takes precedence:
+ a client is built from a copy of that client's settings with
+ the key replaced, and the given client is left untouched.
+
+ Raises:
+ TypeError: if `config` is not a `DiarizationConfig`.
+ """
+ check_config(type(self).__name__, config)
+
+ # Only a client built from `api_key` is owned; `client=None` is the
+ # shared default client, which stays open.
+ self._owns_client = api_key is not None
+ self._client = _client._resolve_client(client, api_key)
+ self.config = config or DiarizationConfig()
+
+ @property
+ def config(self) -> DiarizationConfig:
+ """The default configuration of the `Diarizer`."""
+ return self._config
+
+ @config.setter
+ def config(self, config: DiarizationConfig) -> None:
+ check_config(type(self).__name__, config)
+
+ self._config = config or DiarizationConfig()
+
+ @property
+ def client(self) -> _client.Client:
+ """The `Client` this instance sends requests with."""
+
+ return self._client
+
+ def diarize(
+ self,
+ audio: AudioInput,
+ transcript: Optional[TranscriptInput] = None,
+ config: Optional[DiarizationConfig] = None,
+ *,
+ content_type: Optional[str] = None,
+ ) -> DiarizationResponse:
+ """
+ Labels the speakers in `audio`.
+
+ Args:
+ audio: a local file path, raw bytes, or a binary file object. Not
+ a URL.
+ transcript: the words to label: a `SyncTranscriptResponse`
+ (requested with `timestamps=True`), a dict with a `words`
+ list, or a list of words, each with `text`, `start` and
+ `end` in milliseconds. `None` runs segments-only mode:
+ `words` and `utterances` come back empty.
+ config: Options for this request. Replaces (does not merge with)
+ the instance's default `config`.
+ content_type: the audio's Content-Type, which selects the
+ decoder. Inferred from the file extension when absent:
+ `audio/wav`, `audio/pcm` (`.pcm`/`.raw`, or whenever
+ `sample_rate`/`channels` are set), `audio/mpeg`,
+ `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`; WAV
+ when there is no known extension.
+
+ Returns: a `DiarizationResponse`.
+
+ Raises:
+ DiarizationError: on any API refusal.
+ ValueError: for a URL, or raw PCM missing `sample_rate` or `channels`.
+ TypeError: for an unsupported audio or transcript type.
+ """
+ data, filename, audio_content_type, transcript_json, config_json = (
+ resolve_request(
+ type(self).__name__,
+ audio,
+ transcript,
+ config or self._config,
+ content_type,
+ )
+ )
+
+ return api.diarize(
+ self._client.http_client,
+ base_url=self._client.settings.diarization_base_url,
+ audio=data,
+ filename=filename,
+ audio_content_type=audio_content_type,
+ transcript=transcript_json,
+ config=config_json,
+ timeout=self._client.settings.diarization_http_timeout,
+ )
+
+ def close(self) -> None:
+ """
+ Closes the HTTP pool this instance owns. A `client` you passed is
+ left open.
+ """
+
+ if self._owns_client:
+ self._client.close()
+
+ def __enter__(self) -> "Diarizer":
+ return self
+
+ def __exit__(self, *exc: object) -> None:
+ self.close()
diff --git a/assemblyai/diarization/v1/models.py b/assemblyai/diarization/v1/models.py
new file mode 100644
index 0000000..9961645
--- /dev/null
+++ b/assemblyai/diarization/v1/models.py
@@ -0,0 +1,169 @@
+"""Models for the Diarization API.
+
+The request options, the result and the error of `/v1/diarize` on
+`diarization.assemblyai.com`, alongside the client that uses them.
+"""
+
+from typing import List, Optional
+
+from ...types import AssemblyAIError, BaseModel, ConfigDict, Field, pydantic_v2
+
+__all__ = [
+ "DiarizationConfig",
+ "DiarizationError",
+ "DiarizationResponse",
+ "DiarizationSegment",
+ "DiarizationUtterance",
+ "DiarizedWord",
+]
+
+
+class DiarizationError(AssemblyAIError):
+ """
+ Error raised when a Diarization API request fails.
+
+ Carries a machine-readable `error_code`, the snake_cased problem-details
+ `title` from the server (e.g. `unauthorized`, `bad_request`,
+ `audio_too_large`), when present, and `retry_after` (seconds) for 429/503
+ responses that include a `Retry-After` header. `status_code` is `401` for
+ a missing or invalid key and `400` for a request the API rejects
+ (an unknown config field, a transcript without `words`).
+ """
+
+ def __init__(
+ self,
+ message: str,
+ status_code: Optional[int] = None,
+ error_code: Optional[str] = None,
+ retry_after: Optional[int] = None,
+ ):
+ super().__init__(message, status_code)
+ self.error_code = error_code
+ self.retry_after = retry_after
+
+
+class DiarizationConfig(BaseModel):
+ """
+ Options for a Diarization API request.
+
+ `sample_rate` and `channels` are required only for raw PCM audio;
+ container formats carry them in their own headers.
+
+ Unknown fields are rejected rather than silently dropped: the API
+ accepts this exact set and answers `400` to anything else.
+ """
+
+ sample_rate: Optional[int] = None
+ """Source sample rate in Hz. Setting either this or `channels` marks the
+ audio as raw 16-bit PCM, and both are then required."""
+
+ channels: Optional[int] = None
+ """Channel count (1 mono, 2 stereo). Setting either this or `sample_rate`
+ marks the audio as raw 16-bit PCM, and both are then required."""
+
+ language_code: Optional[str] = None
+ """A bare language code such as `en` or `es` (default `en`). Decides
+ whether the words of one sentence are voted onto one speaker. Unused
+ without a transcript."""
+
+ if pydantic_v2:
+ model_config = ConfigDict(extra="forbid")
+ else:
+
+ class Config:
+ extra = "forbid"
+
+
+class DiarizedWord(BaseModel):
+ """A transcript word with the speaker who said it."""
+
+ text: str
+ "The text of the word."
+
+ start: int
+ "Word start in milliseconds."
+
+ end: int
+ "Word end in milliseconds."
+
+ confidence: Optional[float] = None
+ "The word's transcription confidence, when the transcript carried one."
+
+ speaker: str
+ "The speaker label: `A`, `B`, and so on."
+
+ speaker_confidence: Optional[float] = None
+ "Confidence in the speaker label, 0-1. `None` when unavailable."
+
+
+class DiarizationUtterance(BaseModel):
+ """A run of consecutive words by one speaker."""
+
+ speaker: str
+ "The speaker label."
+
+ start: int
+ "Start of the first word in milliseconds."
+
+ end: int
+ "End of the last word in milliseconds."
+
+ text: str
+ "The words' text, joined."
+
+ confidence: Optional[float] = None
+ "Mean word confidence."
+
+ speaker_confidence: Optional[float] = None
+ "Mean word speaker confidence. `None` unless every word carries one."
+
+ words: List[DiarizedWord] = Field(default_factory=list)
+ "The utterance's words."
+
+
+class DiarizationSegment(BaseModel):
+ """One of the model's speaker turns."""
+
+ start: int
+ "Segment start in milliseconds."
+
+ end: int
+ "Segment end in milliseconds."
+
+ speaker: str
+ "The speaker label, the same speaker as in `words`."
+
+ speaker_confidence: Optional[float] = None
+ "The segment's calibrated confidence. `None` when unavailable."
+
+
+class DiarizationResponse(BaseModel):
+ """
+ The result of a Diarization API request.
+
+ Without a transcript, `words` and `utterances` are empty and `segments`
+ and `speakers` are filled. `speakers` lists only the speakers words went
+ to when there are words; a speaker no word went to appears in `segments`
+ alone.
+ """
+
+ words: List[DiarizedWord] = Field(default_factory=list)
+ "The transcript's words, each with a speaker."
+
+ utterances: List[DiarizationUtterance] = Field(default_factory=list)
+ "Runs of consecutive words by one speaker."
+
+ segments: List[DiarizationSegment] = Field(default_factory=list)
+ "The model's speaker turns, sorted by start."
+
+ speakers: List[str] = Field(default_factory=list)
+ "The sorted speaker labels."
+
+ audio_duration_ms: int
+ "Total audio duration in milliseconds."
+
+ session_id: str
+ "Server-generated UUID for this request. Record it to correlate with support."
+
+ request_time_ms: Optional[float] = None
+ "End-to-end server-side request time in milliseconds."
diff --git a/assemblyai/types.py b/assemblyai/types.py
index 4c36780..e01e244 100644
--- a/assemblyai/types.py
+++ b/assemblyai/types.py
@@ -156,6 +156,12 @@ class Settings(BaseSettings):
producing audio is not counted. Sized to outlast the final segment's
inference plus the LLM pass over the transcript."""
+ diarization_base_url: str = "https://diarization.assemblyai.com"
+ "The base URL for the Diarization API (used by `Diarizer`/`AsyncDiarizer`). Set `https://diarization.us.assemblyai.com` or `https://diarization.eu.assemblyai.com` to keep requests in the US or EU data zone."
+
+ diarization_http_timeout: float = 330.0
+ "The HTTP timeout for Diarization API requests. Above the API's own 300-second inference limit plus its queue wait, so a request that reaches it gets the API's `504` as a `DiarizationError`, not a client timeout."
+
llm_gateway_base_url: str = "https://llm-gateway.assemblyai.com"
"The base URL for the LLM Gateway API (used by `LLMGateway`/`AsyncLLMGateway`)"
diff --git a/docs/check_api_docs.py b/docs/check_api_docs.py
index b9a0f58..7ce56ea 100644
--- a/docs/check_api_docs.py
+++ b/docs/check_api_docs.py
@@ -17,6 +17,7 @@
"assemblyai/prerecorded/v2.html",
"assemblyai/sync/v1.html",
"assemblyai/dictation/v1.html",
+ "assemblyai/diarization/v1.html",
"assemblyai/llm_gateway/v1.html",
"assemblyai/streaming/v3.html",
"assemblyai/tts/v1.html",
@@ -26,6 +27,7 @@
"Transcriber",
"SyncTranscriber",
"DictationTranscriber",
+ "Diarizer",
"LLMGateway",
"RealTimeTranscriber",
"TTSSession",
@@ -35,6 +37,7 @@
"Transcriber.transcribe",
"SyncTranscriber.transcribe",
"DictationTranscriber.transcribe_live",
+ "Diarizer.diarize",
"LLMGateway.chat",
"RealTimeTranscriber.stream",
"TTSSession.speak",
diff --git a/scripts/build_api_docs.sh b/scripts/build_api_docs.sh
index 16024b3..6372ff5 100755
--- a/scripts/build_api_docs.sh
+++ b/scripts/build_api_docs.sh
@@ -8,5 +8,6 @@ pdoc -o docs/api \
assemblyai.prerecorded.v2 \
assemblyai.sync.v1 \
assemblyai.dictation.v1 \
+ assemblyai.diarization.v1 \
assemblyai.llm_gateway.v1 \
assemblyai.tts.v1
diff --git a/tests/unit/test_diarization.py b/tests/unit/test_diarization.py
new file mode 100644
index 0000000..e646c16
--- /dev/null
+++ b/tests/unit/test_diarization.py
@@ -0,0 +1,437 @@
+"""Tests for the Diarization API client.
+
+Every call posts one buffered multipart body (`config`, `transcript`,
+`audio`) to `/v1/diarize` on the diarization host and parses the JSON result.
+"""
+
+import email
+import io
+import json
+from typing import Any, Dict, List
+
+import httpx
+import pytest
+from pytest_httpx import HTTPXMock
+
+import assemblyai as aai
+
+aai.settings.api_key = "test"
+
+DIARIZE_URL = f"{aai.settings.diarization_base_url}/v1/diarize"
+
+_WORDS: List[Dict[str, Any]] = [
+ {"text": "hello", "start": 0, "end": 400, "confidence": 0.9},
+ {"text": "hi", "start": 4400, "end": 4700, "confidence": 0.95},
+]
+
+_OK_RESPONSE = {
+ "words": [
+ {**_WORDS[0], "speaker": "A", "speaker_confidence": 0.93},
+ {**_WORDS[1], "speaker": "B"},
+ ],
+ "utterances": [
+ {
+ "speaker": "A",
+ "start": 0,
+ "end": 400,
+ "text": "hello",
+ "confidence": 0.9,
+ "speaker_confidence": 0.93,
+ "words": [{**_WORDS[0], "speaker": "A", "speaker_confidence": 0.93}],
+ },
+ {
+ "speaker": "B",
+ "start": 4400,
+ "end": 4700,
+ "text": "hi",
+ "confidence": 0.95,
+ "words": [{**_WORDS[1], "speaker": "B"}],
+ },
+ ],
+ "segments": [
+ {"start": 0, "end": 4200, "speaker": "A", "speaker_confidence": 0.93},
+ {"start": 4350, "end": 9100, "speaker": "B"},
+ ],
+ "speakers": ["A", "B"],
+ "audio_duration_ms": 9500,
+ "session_id": "eb92c4ff-4bbb-429f-9b99-7279d7fe738f",
+ "request_time_ms": 312.4,
+}
+
+_SEGMENTS_ONLY = {**_OK_RESPONSE, "words": [], "utterances": []}
+
+
+def _mock_ok(httpx_mock: HTTPXMock, body: dict = _OK_RESPONSE, url: str = DIARIZE_URL):
+ httpx_mock.add_response(
+ url=url, method="POST", status_code=httpx.codes.OK, json=body
+ )
+
+
+def _parts(request: httpx.Request) -> dict:
+ """The recorded multipart body as {name: email part}, in order."""
+
+ raw = b"Content-Type: " + request.headers["content-type"].encode() + b"\r\n\r\n"
+ message = email.message_from_bytes(raw + request.read())
+ return {
+ part.get_param("name", header="content-disposition"): part
+ for part in message.get_payload()
+ }
+
+
+def _json_part(part) -> dict:
+ assert part.get_content_type() == "application/json"
+ return json.loads(part.get_payload(decode=True))
+
+
+def _sent(httpx_mock: HTTPXMock) -> dict:
+ requests = httpx_mock.get_requests()
+ assert len(requests) == 1
+ return _parts(requests[0])
+
+
+def test_diarize_with_a_transcript(httpx_mock: HTTPXMock):
+ # GIVEN a diarization host that labels the words
+ _mock_ok(httpx_mock)
+
+ # WHEN WAV audio is diarized with a word list
+ result = aai.Diarizer().diarize(b"RIFF....", transcript={"words": _WORDS})
+
+ # THEN one buffered request carried the raw key, the transcript and audio
+ request = httpx_mock.get_requests()[0]
+ assert str(request.url) == DIARIZE_URL
+ assert request.headers["authorization"] == "test"
+ assert "content-length" in request.headers
+ parts = _sent(httpx_mock)
+ assert list(parts) == ["transcript", "audio"]
+ assert _json_part(parts["transcript"]) == {"words": _WORDS}
+ assert parts["audio"].get_content_type() == "audio/wav"
+ assert parts["audio"].get_payload(decode=True) == b"RIFF...."
+
+ # AND the result is parsed
+ assert isinstance(result, aai.DiarizationResponse)
+ assert [w.speaker for w in result.words] == ["A", "B"]
+ assert result.words[0].speaker_confidence == 0.93
+ assert result.words[1].speaker_confidence is None
+ assert result.utterances[1].text == "hi"
+ assert result.utterances[0].words[0].text == "hello"
+ assert result.segments[1].speaker_confidence is None
+ assert result.speakers == ["A", "B"]
+ assert result.audio_duration_ms == 9500
+ assert result.session_id == _OK_RESPONSE["session_id"]
+
+
+def test_diarize_without_a_transcript_runs_segments_only(httpx_mock: HTTPXMock):
+ # GIVEN a host answering segments only
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+
+ # WHEN audio is diarized alone
+ result = aai.Diarizer().diarize(b"RIFF....")
+
+ # THEN neither a transcript nor a config part was sent
+ assert list(_sent(httpx_mock)) == ["audio"]
+
+ # AND the segments and speakers come back with no words
+ assert result.words == [] and result.utterances == []
+ assert [s.speaker for s in result.segments] == ["A", "B"]
+ assert result.speakers == ["A", "B"]
+
+
+def test_diarize_sends_an_explicit_empty_word_list(httpx_mock: HTTPXMock):
+ # GIVEN a host answering empty lists
+ _mock_ok(httpx_mock, {**_SEGMENTS_ONLY, "segments": [], "speakers": []})
+
+ # WHEN an empty word list is passed
+ aai.Diarizer().diarize(b"RIFF", transcript=[])
+
+ # THEN it is sent, not mistaken for segments-only mode
+ assert _json_part(_sent(httpx_mock)["transcript"]) == {"words": []}
+
+
+def test_diarize_accepts_a_sync_transcript_response(httpx_mock: HTTPXMock):
+ # GIVEN a sync transcription result with timestamps
+ _mock_ok(httpx_mock)
+ transcript = aai.SyncTranscriptResponse(
+ text="hello hi",
+ words=[aai.SyncWord(**w) for w in _WORDS],
+ confidence=0.92,
+ audio_duration_ms=9500,
+ session_id="sync-session",
+ )
+
+ # WHEN it is passed as the transcript
+ aai.Diarizer().diarize(b"RIFF", transcript=transcript)
+
+ # THEN its words are sent
+ assert _json_part(_sent(httpx_mock)["transcript"]) == {"words": _WORDS}
+
+
+def test_diarize_accepts_a_list_of_words(httpx_mock: HTTPXMock):
+ # GIVEN a mix of SyncWord and dict words, one without timestamps
+ _mock_ok(httpx_mock)
+ words: List[Any] = [aai.SyncWord(text="hello", confidence=0.9), _WORDS[1]]
+
+ # WHEN the list is passed
+ aai.Diarizer().diarize(b"RIFF", transcript=words)
+
+ # THEN the unset timings are left out for the API to fill
+ assert _json_part(_sent(httpx_mock)["transcript"]) == {
+ "words": [{"text": "hello", "confidence": 0.9}, _WORDS[1]]
+ }
+
+
+@pytest.mark.parametrize("transcript", ["hello hi", 42])
+def test_diarize_rejects_other_transcript_types(transcript):
+ with pytest.raises(TypeError, match="transcript must be"):
+ aai.Diarizer().diarize(b"RIFF", transcript=transcript)
+
+
+def test_diarize_pcm_sends_config_and_pcm_content_type(httpx_mock: HTTPXMock):
+ # GIVEN raw PCM settings
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ config = aai.DiarizationConfig(sample_rate=16000, channels=1, language_code="es")
+
+ # WHEN raw bytes are diarized
+ aai.Diarizer().diarize(b"\x00\x01" * 160, config=config)
+
+ # THEN the config precedes the audio, which is labelled audio/pcm
+ parts = _sent(httpx_mock)
+ assert list(parts) == ["config", "audio"]
+ assert _json_part(parts["config"]) == {
+ "sample_rate": 16000,
+ "channels": 1,
+ "language_code": "es",
+ }
+ assert parts["audio"].get_content_type() == "audio/pcm"
+ assert parts["audio"].get_filename() == "audio.pcm"
+
+
+def test_diarize_pcm_requires_rate_and_channels(tmp_path):
+ path = tmp_path / "call.pcm"
+ path.write_bytes(b"\x00\x01")
+
+ with pytest.raises(ValueError, match="sample_rate and channels"):
+ aai.Diarizer().diarize(path)
+
+
+@pytest.mark.parametrize(
+ "name, content_type",
+ [
+ ("call.mp3", "audio/mpeg"),
+ ("call.flac", "audio/flac"),
+ ("call.ogg", "audio/ogg"),
+ ("call.mp4", "audio/mp4"),
+ ("call.webm", "audio/webm"),
+ ("call.wav", "audio/wav"),
+ ("call.unknown", "audio/wav"),
+ ],
+)
+def test_diarize_infers_the_content_type_from_the_extension(
+ httpx_mock: HTTPXMock, tmp_path, name, content_type
+):
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ path = tmp_path / name
+ path.write_bytes(b"audio")
+
+ aai.Diarizer().diarize(str(path))
+
+ audio = _sent(httpx_mock)["audio"]
+ assert audio.get_content_type() == content_type
+ assert audio.get_filename() == name
+
+
+def test_diarize_names_a_file_object(httpx_mock: HTTPXMock, tmp_path):
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ path = tmp_path / "call.mp3"
+ path.write_bytes(b"ID3")
+
+ with open(path, "rb") as f:
+ aai.Diarizer().diarize(f)
+
+ assert _sent(httpx_mock)["audio"].get_content_type() == "audio/mpeg"
+
+
+def test_diarize_content_type_override_wins(httpx_mock: HTTPXMock):
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+
+ aai.Diarizer().diarize(io.BytesIO(b"OggS"), content_type="audio/ogg")
+
+ assert _sent(httpx_mock)["audio"].get_content_type() == "audio/ogg"
+
+
+def test_diarize_rejects_a_url():
+ with pytest.raises(ValueError, match="does not accept URLs"):
+ aai.Diarizer().diarize("https://example.com/call.wav")
+
+
+def test_config_rejects_unknown_fields():
+ with pytest.raises(ValueError):
+ aai.DiarizationConfig(speakers_expected=2)
+
+
+def test_rejects_other_products_configs():
+ with pytest.raises(TypeError, match="expects DiarizationConfig"):
+ aai.Diarizer(config=aai.SyncTranscriptionConfig())
+ with pytest.raises(TypeError, match="expects DiarizationConfig"):
+ aai.Diarizer().diarize(b"RIFF", config=aai.DictationConfig())
+
+
+def test_default_config_and_per_call_override(httpx_mock: HTTPXMock):
+ # GIVEN a diarizer with a default config
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ diarizer = aai.Diarizer(config=aai.DiarizationConfig(language_code="de"))
+
+ # WHEN one call uses it and one overrides it
+ diarizer.diarize(b"RIFF")
+ diarizer.diarize(b"RIFF", config=aai.DiarizationConfig(language_code="fr"))
+
+ # THEN the override replaces the default
+ first, second = httpx_mock.get_requests()
+ assert _json_part(_parts(first)["config"]) == {"language_code": "de"}
+ assert _json_part(_parts(second)["config"]) == {"language_code": "fr"}
+
+
+def test_unauthorized_maps_to_diarization_error(httpx_mock: HTTPXMock):
+ # GIVEN a missing key, which the API answers with a problem+json 401
+ httpx_mock.add_response(
+ url=DIARIZE_URL,
+ method="POST",
+ status_code=401,
+ json={
+ "status": 401,
+ "title": "Unauthorized",
+ "detail": "Missing Authorization header",
+ },
+ headers={"content-type": "application/problem+json"},
+ )
+
+ # WHEN diarizing, THEN a DiarizationError carries status, code and detail
+ with pytest.raises(aai.DiarizationError) as exc_info:
+ aai.Diarizer().diarize(b"RIFF")
+
+ error = exc_info.value
+ assert error.status_code == 401
+ assert error.error_code == "unauthorized"
+ assert "Missing Authorization header" in str(error)
+ assert isinstance(error, aai.AssemblyAIError)
+ assert not isinstance(error, aai.SyncTranscriptError)
+
+
+@pytest.mark.parametrize(
+ "status, title, code",
+ [
+ (400, "Bad Request", "bad_request"),
+ (411, "Length Required", "length_required"),
+ (413, "Audio Too Large", "audio_too_large"),
+ (415, "Unsupported Media Type", "unsupported_media_type"),
+ (504, "Inference Timeout", "inference_timeout"),
+ ],
+)
+def test_problem_details_map_to_diarization_error(
+ httpx_mock: HTTPXMock, status, title, code
+):
+ httpx_mock.add_response(
+ url=DIARIZE_URL,
+ method="POST",
+ status_code=status,
+ json={"status": status, "title": title, "detail": "nope"},
+ headers={"content-type": "application/problem+json"},
+ )
+
+ with pytest.raises(aai.DiarizationError) as exc_info:
+ aai.Diarizer().diarize(b"RIFF", transcript={"words": _WORDS})
+
+ assert exc_info.value.status_code == status
+ assert exc_info.value.error_code == code
+ assert "nope" in str(exc_info.value)
+
+
+def test_capacity_error_surfaces_retry_after(httpx_mock: HTTPXMock):
+ httpx_mock.add_response(
+ url=DIARIZE_URL,
+ method="POST",
+ status_code=503,
+ json={"status": 503, "title": "Capacity Exceeded", "detail": "busy"},
+ headers={"Retry-After": "2"},
+ )
+
+ with pytest.raises(aai.DiarizationError) as exc_info:
+ aai.Diarizer().diarize(b"RIFF")
+
+ assert exc_info.value.error_code == "capacity_exceeded"
+ assert exc_info.value.retry_after == 2
+
+
+def test_non_json_error_keeps_the_status(httpx_mock: HTTPXMock):
+ httpx_mock.add_response(
+ url=DIARIZE_URL, method="POST", status_code=502, text="Bad Gateway"
+ )
+
+ with pytest.raises(aai.DiarizationError) as exc_info:
+ aai.Diarizer().diarize(b"RIFF")
+
+ assert exc_info.value.status_code == 502
+ assert "Bad Gateway" in str(exc_info.value)
+
+
+def test_custom_base_url(httpx_mock: HTTPXMock):
+ # GIVEN a client pointed at the EU host
+ eu = "https://diarization.eu.assemblyai.com/"
+ _mock_ok(
+ httpx_mock,
+ _SEGMENTS_ONLY,
+ url="https://diarization.eu.assemblyai.com/v1/diarize",
+ )
+ settings = aai.Settings(api_key="eu-key", diarization_base_url=eu)
+
+ # WHEN diarizing through it
+ client = aai.Client(settings=settings)
+ aai.Diarizer(client=client).diarize(b"RIFF")
+ client.close()
+
+ # THEN the request went to that host with its key
+ request = httpx_mock.get_requests()[0]
+ assert request.url.host == "diarization.eu.assemblyai.com"
+ assert request.headers["authorization"] == "eu-key"
+
+
+def test_uses_the_diarization_timeout(httpx_mock: HTTPXMock):
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+
+ aai.Diarizer().diarize(b"RIFF")
+
+ timeout = httpx_mock.get_requests()[0].extensions["timeout"]
+ assert timeout["read"] == aai.settings.diarization_http_timeout
+
+
+def test_api_key_constructor_builds_own_client(httpx_mock: HTTPXMock):
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+
+ with aai.Diarizer(api_key="per-call-key") as diarizer:
+ diarizer.diarize(b"RIFF")
+
+ assert httpx_mock.get_requests()[0].headers["authorization"] == "per-call-key"
+
+
+def test_response_ignores_unknown_fields(httpx_mock: HTTPXMock):
+ _mock_ok(httpx_mock, {**_SEGMENTS_ONLY, "new_field": 1})
+
+ assert aai.Diarizer().diarize(b"RIFF").audio_duration_ms == 9500
+
+
+def test_diarization_settings_defaults():
+ settings = aai.Settings()
+
+ assert settings.diarization_base_url == "https://diarization.assemblyai.com"
+ assert settings.diarization_http_timeout == 330.0
+
+
+def test_public_names_are_exported():
+ from assemblyai import diarization
+ from assemblyai.diarization import v1
+
+ for name in v1.__all__:
+ assert getattr(diarization, name) is getattr(v1, name)
+ assert aai.Diarizer is v1.Diarizer
+ assert aai.AsyncDiarizer is v1.AsyncDiarizer
+ assert aai.DiarizationError is v1.DiarizationError
diff --git a/tests/unit/test_diarization_async.py b/tests/unit/test_diarization_async.py
new file mode 100644
index 0000000..1ab2304
--- /dev/null
+++ b/tests/unit/test_diarization_async.py
@@ -0,0 +1,125 @@
+"""Tests for the asyncio Diarization API client.
+
+The request shape is covered by `test_diarization.py`; these pin the asyncio
+twin: same route, same parts, same parsing, same errors, and its pool.
+"""
+
+import json
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+import assemblyai as aai
+from tests.unit.test_diarization import (
+ _OK_RESPONSE,
+ _SEGMENTS_ONLY,
+ _WORDS,
+ DIARIZE_URL,
+ _json_part,
+ _mock_ok,
+ _sent,
+)
+
+pytestmark = pytest.mark.asyncio
+
+aai.settings.api_key = "test"
+
+
+async def test_diarize_with_a_sync_transcript(httpx_mock: HTTPXMock):
+ # GIVEN a sync transcription result
+ _mock_ok(httpx_mock)
+ transcript = aai.SyncTranscriptResponse(
+ text="hello hi",
+ words=[aai.SyncWord(**w) for w in _WORDS],
+ confidence=0.92,
+ audio_duration_ms=9500,
+ session_id="sync-session",
+ )
+
+ # WHEN it is diarized asynchronously
+ async with aai.AsyncDiarizer() as diarizer:
+ result = await diarizer.diarize(b"RIFF", transcript=transcript)
+
+ # THEN the same parts were sent and the result parsed
+ parts = _sent(httpx_mock)
+ assert list(parts) == ["transcript", "audio"]
+ assert _json_part(parts["transcript"]) == {"words": _WORDS}
+ assert httpx_mock.get_requests()[0].headers["authorization"] == "test"
+ assert [u.speaker for u in result.utterances] == ["A", "B"]
+ assert result.session_id == _OK_RESPONSE["session_id"]
+
+
+async def test_diarize_segments_only_with_pcm(httpx_mock: HTTPXMock, tmp_path):
+ # GIVEN a raw PCM file
+ _mock_ok(httpx_mock, _SEGMENTS_ONLY)
+ path = tmp_path / "call.raw"
+ path.write_bytes(b"\x00\x01" * 160)
+ config = aai.DiarizationConfig(sample_rate=8000, channels=2)
+
+ # WHEN it is diarized without a transcript
+ async with aai.AsyncDiarizer(config=config) as diarizer:
+ result = await diarizer.diarize(path)
+
+ # THEN config and PCM audio were sent, and segments came back
+ parts = _sent(httpx_mock)
+ assert list(parts) == ["config", "audio"]
+ assert json.loads(parts["config"].get_payload(decode=True)) == {
+ "sample_rate": 8000,
+ "channels": 2,
+ }
+ assert parts["audio"].get_content_type() == "audio/pcm"
+ assert result.words == [] and len(result.segments) == 2
+
+
+async def test_unauthorized_maps_to_diarization_error(httpx_mock: HTTPXMock):
+ httpx_mock.add_response(
+ url=DIARIZE_URL,
+ method="POST",
+ status_code=401,
+ json={"status": 401, "title": "Unauthorized", "detail": "Invalid key"},
+ headers={"content-type": "application/problem+json"},
+ )
+
+ async with aai.AsyncDiarizer() as diarizer:
+ with pytest.raises(aai.DiarizationError) as exc_info:
+ await diarizer.diarize(b"RIFF")
+
+ assert exc_info.value.status_code == 401
+ assert exc_info.value.error_code == "unauthorized"
+
+
+async def test_custom_base_url_on_a_shared_client(httpx_mock: HTTPXMock):
+ # GIVEN a shared client pointed at the US host
+ _mock_ok(
+ httpx_mock,
+ _SEGMENTS_ONLY,
+ url="https://diarization.us.assemblyai.com/v1/diarize",
+ )
+ settings = aai.Settings(
+ api_key="us-key", diarization_base_url="https://diarization.us.assemblyai.com"
+ )
+
+ async with aai.AsyncClient(settings=settings) as client:
+ diarizer = aai.AsyncDiarizer(client=client)
+ await diarizer.diarize(b"RIFF")
+ # WHEN the diarizer is closed, THEN the shared client stays open
+ await diarizer.aclose()
+ assert not client.http_client.is_closed
+
+ assert httpx_mock.get_requests()[0].headers["authorization"] == "us-key"
+
+
+async def test_rejects_other_products_configs():
+ with pytest.raises(TypeError, match="expects DiarizationConfig"):
+ aai.AsyncDiarizer(config=aai.TTSConfig())
+
+ async with aai.AsyncDiarizer() as diarizer:
+ with pytest.raises(TypeError, match="expects DiarizationConfig"):
+ await diarizer.diarize(b"RIFF", config=aai.SyncTranscriptionConfig())
+
+
+async def test_owned_client_is_closed():
+ diarizer = aai.AsyncDiarizer()
+ await diarizer.aclose()
+
+ assert diarizer.client.http_client.is_closed