Async Client

Sync mirror: the synchronous SonioxClient exposes the same API as AsyncSonioxClient below - drop await from each call and treat AsyncIterator[X] return types as plain Iterator[X]. Only the async surface is documented here to avoid duplicating an otherwise identical reference. Realtime sessions have genuinely different sync/async patterns and are documented in the Realtime Client page.

AsyncSonioxClient

Asynchronous Soniox REST client exposing HTTP and realtime helpers.

Parameter	Type	Description
`api_key`	`str \| None`	API key used for authentication.
`api_base_url`	`str \| None`	Base URL for Soniox REST API requests.
`websocket_base_url`	`str \| None`	Base URL for Soniox realtime WebSocket endpoint.
`tts_api_base_url`	`str \| None`	Base URL for Soniox Text-to-Speech REST API requests.
`tts_websocket_base_url`	`str \| None`	Base URL for Soniox Text-to-Speech realtime WebSocket endpoint.
`timeout_sec`	`float \| None`	Maximum wait time in seconds.
`webhook_secret`	`str \| None`	Webhook secret used for signature verification.
`webhook_signature_header`	`str \| None`	Webhook signature header name.
`client_kwargs`	`Any`	Additional HTTP client keyword arguments.

Properties

Property	Type	Description
`files`	`AsyncFilesAPI`	File upload and management API namespace.
`stt`	`AsyncSttAPI`	Speech-to-text API namespace.
`tts`	`AsyncTtsAPI`	Text-to-Speech API namespace.
`models`	`AsyncModelsAPI`	Speech-to-text model listing API namespace.
`tts_models`	`AsyncTtsModelsAPI`	Text-to-Speech model listing API namespace.
`voices`	`AsyncVoicesAPI`	Voice cloning, shared voice listing and voice management API namespace.
`usage_logs`	`AsyncUsageLogsAPI`	Per-request usage log API namespace.
`usage`	`AsyncUsageAPI`	Usage and cost summary API namespace.
`concurrency_limits`	`AsyncConcurrencyLimitsAPI`	Concurrency limit API namespace.
`auth`	`AsyncAuthAPI`	Authentication API namespace.
`webhooks`	`AsyncSonioxWebhooksAPI`	Webhook utilities API namespace.
`realtime`	`AsyncRealtimeAPI`	Realtime websocket API namespace (STT and TTS).

Parameter	Type	Description
`method`	`str`	HTTP method to use for the request.
`path`	`str`	Relative API path for the request.
`params`	`Mapping[str, Any] \| None`	Query parameters for the request.
`json`	`Any \| None`	JSON request payload.
`data`	`Mapping[str, Any] \| None`	Form-encoded request payload.
`files`	`Mapping[str, Any] \| None`	Multipart file payload mapping.

aclose()

aclose() -> None

Close any outstanding async HTTP connections.

Returns

None

AsyncFilesAPI

list()

list(limit: int = 100, cursor: str | None = None) -> GetFilesResponse

List uploaded files.

Performs a GET request to /files with optional pagination.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of files to return.
`cursor`	`str \| None`	Pagination cursor for the next page of results.

Returns

GetFilesResponse

Raises

SonioxAPIError When the API returns an error.

count()

count() -> GetFilesCountResponse

Return a breakdown of uploaded file counts.

Performs a GET request to /files/count.

Returns

GetFilesCountResponse

Raises

SonioxAPIError When the API returns an error.

list_all()

list_all(limit: int = 100) -> AsyncGenerator[File, None]

Iterate through all uploaded files across all pages.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of files to return.

Yields

AsyncGenerator[File, None]

File: The next file object from the API.

Raises

SonioxAPIError When the API returns an error.

get()

get(file_id: str) -> File

Retrieve a file by ID.

Performs a GET request to /files/{file_id}.

Parameters

Parameter	Type	Description
`file_id`	`str`	ID of a previously uploaded file.

Returns

File

Raises

SonioxAPIError When the API returns an error.

get_or_none()

get_or_none(file_id: str) -> File | None

Retrieve a file by ID.

Returns None if the file does not exist.

Parameters

Parameter	Type	Description
`file_id`	`str`	ID of a previously uploaded file.

Returns

File | None

Raises

SonioxAPIError When the API returns an error.

delete()

delete(file_id: str) -> None

Delete a file by ID.

Performs a DELETE request to /files/{file_id}.

Parameters

Parameter	Type	Description
`file_id`	`str`	ID of a previously uploaded file.

Returns

None

Raises

SonioxAPIError When the API returns an error.

delete_if_exists()

delete_if_exists(file_id: str) -> None

Delete a file by ID if it exists.

Ignores missing files.

Parameters

Parameter	Type	Description
`file_id`	`str`	ID of a previously uploaded file.

Returns

None

Raises

SonioxAPIError When the API returns an error.

upload()

upload(file: BinaryIO | bytes | Path | str, *, filename: str | None = None, client_reference_id: str | None = None) -> File

Upload a file.

Performs a multipart POST request to /files.

Uploaded files are automatically deleted 30 days after upload.

Parameters

Parameter	Type	Description
`file`	`BinaryIO \| bytes \| Path \| str`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier string. Does not need to be unique

Returns

File

Raises

SonioxAPIError When the API returns an error.

delete_all()

delete_all(limit: int = 100) -> None

Delete all files.

Iterates through all pages and deletes each file. Stops and raises on the first failed deletion.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of files to return.

Returns

None

Raises

SonioxAPIError When the API returns an error.

AsyncSttAPI

list()

list(limit: int = 100, cursor: str | None = None) -> GetTranscriptionsResponse

List transcriptions.

Performs a GET request to /transcriptions with optional pagination.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of transcriptions to return.
`cursor`	`str \| None`	Pagination cursor for the next page of results.

Returns

GetTranscriptionsResponse

Raises

SonioxAPIError When the API returns an error.

count()

count() -> GetTranscriptionsCountResponse

Return a breakdown of transcription counts.

Performs a GET request to /transcriptions/count.

Returns

GetTranscriptionsCountResponse

Raises

SonioxAPIError When the API returns an error.

list_all()

list_all(limit: int = 100) -> AsyncGenerator[Transcription, None]

Iterate through all transcriptions across all pages.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of transcriptions to return.

Yields

AsyncGenerator[Transcription, None]

File: The next transcription object from the API.

Raises

SonioxAPIError When the API returns an error.

delete_all()

delete_all(limit: int = 100) -> None

Delete all transcriptions.

Iterates through all pages and deletes each transcription. Stops and raises on the first failed deletion.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of transcriptions to return.

Returns

None

Raises

SonioxAPIError When the API returns an error.

create()

create(*, model: str = DEFAULT_MODEL, file_id: str | None = None, audio_url: str | None = None, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Create a transcription.

Performs a POST request to /transcriptions.

Transcriptions are automatically deleted 30 days after creation.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`file_id`	`str \| None`	ID of a previously uploaded file.
`audio_url`	`str \| None`	Publicly accessible audio URL.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

get()

get(transcription_id: str) -> Transcription

Retrieve a transcription by ID.

Performs a GET request to /transcriptions/{transcription_id}.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

get_or_none()

get_or_none(transcription_id: str) -> Transcription | None

Retrieve a transcription by ID.

Returns None if the transcription does not exist.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

Transcription | None

Raises

SonioxAPIError When the API returns an error.

delete()

delete(transcription_id: str) -> None

Delete a transcription by ID.

Performs a DELETE request to /transcriptions/{transcription_id}.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

None

Raises

SonioxAPIError When the API returns an error.

delete_if_exists()

delete_if_exists(transcription_id: str) -> None

Delete a transcription by ID if it exists.

Ignores missing transcriptions.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

None

Raises

SonioxAPIError When the API returns an error.

destroy()

destroy(transcription_id: str) -> None

Delete a transcription and its associated uploaded file.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

None

Raises

SonioxAPIError When the API returns an error.

destroy_all()

destroy_all(limit: int = 100) -> None

Delete all transcriptions and their associated files. Stops and raises on the first failed deletion.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of transcriptions to return.

Returns

None

Raises

SonioxAPIError When the API returns an error during listing.

get_transcript()

get_transcript(transcription_id: str) -> TranscriptionTranscript

Retrieve the transcript for a transcription.

Performs a GET request to /transcriptions/{transcription_id}/transcript.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.

Returns

TranscriptionTranscript

Raises

SonioxAPIError When the API returns an error.

wait()

wait(transcription_id: str, *, interval_sec: float = 5.0, timeout_sec: float | None = None) -> Transcription

Poll a transcription until it leaves the queued or processing state.

Parameters

Parameter	Type	Description
`transcription_id`	`str`	Transcription identifier.
`interval_sec`	`float`	Polling interval in seconds.
`timeout_sec`	`float \| None`	Maximum wait time in seconds.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
TimeoutError Waiting for the transcription to finish exceeded timeout_sec.

transcribe_from_url()

transcribe_from_url(*, model: str = DEFAULT_MODEL, audio_url: str, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Create a transcription from an audio URL.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`audio_url`	`str`	Publicly accessible audio URL.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

transcribe_from_file_id()

transcribe_from_file_id(*, model: str = DEFAULT_MODEL, file_id: str, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Create a transcription from an existing uploaded file.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`file_id`	`str`	ID of a previously uploaded file.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

transcribe_from_file()

transcribe_from_file(*, model: str = DEFAULT_MODEL, file: BinaryIO | bytes | Path | str, filename: str | None = None, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Upload a file and create a transcription from it.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`file`	`BinaryIO \| bytes \| Path \| str`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

transcribe()

transcribe(*, model: str = DEFAULT_MODEL, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Create a transcription from a file, file ID, or audio URL.

Validates mutually exclusive inputs before submission.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload fails validation.

transcribe_file_with_webhook()

transcribe_file_with_webhook(*, model: str = DEFAULT_MODEL, file: BinaryIO | bytes | Path | str, webhook_url: str, filename: str | None = None, client_reference_id: str | None = None, webhook_auth: WebhookAuthConfig | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Upload a file, configure a webhook, and start transcription.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`file`	`BinaryIO \| bytes \| Path \| str`	File input to upload or transcribe.
`webhook_url`	`str`	URL to receive webhook notifications.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`webhook_auth`	`WebhookAuthConfig \| None`	Webhook authentication configuration.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.

transcribe_and_wait()

transcribe_and_wait(*, model: str = DEFAULT_MODEL, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, client_reference_id: str | None = None, delete_after: bool = False, wait_interval_sec: float = 5.0, wait_timeout_sec: float | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Create a transcription and wait for completion.

Returns a Transcription object after it is completed. Optionally deletes the transcription and the uploaded file after completion.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`delete_after`	`bool`	Whether to delete created resources after completion.
`wait_interval_sec`	`float`	Polling interval in seconds while waiting.
`wait_timeout_sec`	`float \| None`	Maximum wait time in seconds while polling.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload fails validation.
TimeoutError Waiting for the transcription to finish exceeded timeout_sec.

transcribe_and_wait_with_tokens()

transcribe_and_wait_with_tokens(*, model: str = DEFAULT_MODEL, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, client_reference_id: str | None = None, delete_after: bool = False, wait_interval_sec: float = 5.0, wait_timeout_sec: float | None = None, config: CreateTranscriptionConfig | None = None) -> TranscriptionTranscript

Create a transcription, wait for completion, and return the transcript.

Optionally deletes the transcription and uploaded file after completion.

Parameters

Parameter	Type	Description
`model`	`str`	Speech-to-text model to use.
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`delete_after`	`bool`	Whether to delete created resources after completion.
`wait_interval_sec`	`float`	Polling interval in seconds while waiting.
`wait_timeout_sec`	`float \| None`	Maximum wait time in seconds while polling.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

TranscriptionTranscript

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload fails validation.
TimeoutError Waiting for the transcription to finish exceeded timeout_sec.

translate_from_url()

translate_from_url(*, audio_url: str, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Translate audio at a URL.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to.

Parameters

Parameter	Type	Description
`audio_url`	`str`	Publicly accessible audio URL.
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the translate kwargs are invalid.

translate_from_file_id()

translate_from_file_id(*, file_id: str, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Translate an already-uploaded file.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to.

Parameters

Parameter	Type	Description
`file_id`	`str`	ID of a previously uploaded file.
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the translate kwargs are invalid.

translate_from_file()

translate_from_file(*, file: BinaryIO | bytes | Path | str, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, filename: str | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Upload a file and translate it.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to.

Parameters

Parameter	Type	Description
`file`	`BinaryIO \| bytes \| Path \| str`	File input to upload or transcribe.
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`filename`	`str \| None`	Filename associated with uploaded file data.
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the translate kwargs are invalid.

translate()

translate(*, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Translate audio from a file, file ID, or URL.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to. Convenience over transcribe() that fills in the translation config and forces enable_language_identification=True.

Parameters

Parameter	Type	Description
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload or translate kwargs are invalid.

translate_and_wait()

translate_and_wait(*, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, delete_after: bool = False, wait_interval_sec: float = 5.0, wait_timeout_sec: float | None = None, config: CreateTranscriptionConfig | None = None) -> Transcription

Translate and wait for completion. Returns the finished Transcription.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to.

Parameters

Parameter	Type	Description
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`delete_after`	`bool`	Whether to delete created resources after completion.
`wait_interval_sec`	`float`	Polling interval in seconds while waiting.
`wait_timeout_sec`	`float \| None`	Maximum wait time in seconds while polling.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

Transcription

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload or translate kwargs are invalid.
TimeoutError Waiting for the transcription to finish exceeded wait_timeout_sec.

translate_and_wait_with_tokens()

translate_and_wait_with_tokens(*, to: LanguageCode | None = None, source: LanguageCode | None = None, between: tuple[LanguageCode, LanguageCode] | None = None, audio_url: str | None = None, file_id: str | None = None, file: BinaryIO | bytes | Path | str | None = None, filename: str | None = None, model: str = DEFAULT_MODEL, client_reference_id: str | None = None, delete_after: bool = False, wait_interval_sec: float = 5.0, wait_timeout_sec: float | None = None, config: CreateTranscriptionConfig | None = None) -> TranscriptionTranscript

Translate, wait for completion, and return the transcript with tokens.

Provide exactly one of to (one-way) or between (two-way). source is an optional language hint and is only valid with to. Optionally deletes the transcription and uploaded file after completion.

Parameters

Parameter	Type	Description
`to`	`LanguageCode \| None`	-
`source`	`LanguageCode \| None`	The source term to translate.
`between`	`tuple[LanguageCode, LanguageCode] \| None`	-
`audio_url`	`str \| None`	Publicly accessible audio URL.
`file_id`	`str \| None`	ID of a previously uploaded file.
`file`	`BinaryIO \| bytes \| Path \| str \| None`	File input to upload or transcribe.
`filename`	`str \| None`	Filename associated with uploaded file data.
`model`	`str`	Speech-to-text model to use.
`client_reference_id`	`str \| None`	Optional tracking identifier.
`delete_after`	`bool`	Whether to delete created resources after completion.
`wait_interval_sec`	`float`	Polling interval in seconds while waiting.
`wait_timeout_sec`	`float \| None`	Maximum wait time in seconds while polling.
`config`	`CreateTranscriptionConfig \| None`	Configuration options for this operation.

Returns

TranscriptionTranscript

Raises

SonioxAPIError When the API returns an error.
SonioxValidationError When the payload or translate kwargs are invalid.
TimeoutError Waiting for the transcription to finish exceeded wait_timeout_sec.

AsyncTtsAPI

Constructor

AsyncTtsAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

generate()

generate(*, text: str, voice: str, model: str = DEFAULT_MODEL, config: CreateTtsConfig | None = None, language: str | None = None, audio_format: TtsAudioFormat | None = None, sample_rate: TtsSampleRate | None = None, bitrate: TtsBitrate | None = None) -> bytes

Generate speech audio from text and return raw audio bytes.

Performs a POST request to the TTS REST endpoint.

audio_format/sample_rate/bitrate are deprecated; set them on CreateTtsConfig instead. Pass language explicitly — relying on the default ("en") is deprecated and language will be required in the next major release.

Parameters

Parameter	Type	Description
`text`	`str`	Longer free-form background text, prior interaction history, reference documents, or meeting notes.
`voice`	`str`	Voice identifier to generate speech audio with.
`model`	`str`	Speech-to-text model to use.
`config`	`CreateTtsConfig \| None`	Configuration options for this operation.
`language`	`str \| None`	Language code for Text-to-Speech (e.g., "en").
`audio_format`	`TtsAudioFormat \| None`	Audio format for realtime transcription.
`sample_rate`	`TtsSampleRate \| None`	Audio sample rate in Hz.
`bitrate`	`TtsBitrate \| None`	Output bitrate in bits-per-second for compressed formats.

Returns

bytes

Raises

SonioxAPIError When the API returns an error.

generate_to_file()

generate_to_file(output: BinaryIO | Path | str, *, text: str, voice: str = DEFAULT_VOICE, model: str = DEFAULT_MODEL, config: CreateTtsConfig | None = None, language: str | None = None, audio_format: TtsAudioFormat | None = None, sample_rate: TtsSampleRate | None = None, bitrate: TtsBitrate | None = None) -> int

Generate speech audio from text and write the audio bytes to a file-like output.

Parameters

Parameter	Type	Description
`output`	`BinaryIO \| Path \| str`	-
`text`	`str`	Longer free-form background text, prior interaction history, reference documents, or meeting notes.
`voice`	`str`	Voice identifier to generate speech audio with.
`model`	`str`	Speech-to-text model to use.
`config`	`CreateTtsConfig \| None`	Configuration options for this operation.
`language`	`str \| None`	Language code for Text-to-Speech (e.g., "en").
`audio_format`	`TtsAudioFormat \| None`	Audio format for realtime transcription.
`sample_rate`	`TtsSampleRate \| None`	Audio sample rate in Hz.
`bitrate`	`TtsBitrate \| None`	Output bitrate in bits-per-second for compressed formats.

Returns

int

Number of bytes written.

AsyncTtsModelsAPI

Constructor

AsyncTtsModelsAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

list()

list() -> GetTtsModelsResponse

List available Text-to-Speech models.

Performs a GET request to /tts-models.

Returns

GetTtsModelsResponse

Raises

SonioxAPIError When the API returns an error.

AsyncVoicesAPI

Constructor

AsyncVoicesAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

list()

list(limit: int = 100, cursor: str | None = None) -> GetVoicesResponse

List the voices you cloned in the project.

For the built-in voices of a model, use list_shared().

Performs a GET request to /voices with optional pagination.

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of voices to return.
`cursor`	`str \| None`	Pagination cursor for the next page of results.

Returns

GetVoicesResponse

Raises

SonioxAPIError When the API returns an error.

count()

count() -> GetVoicesCountResponse

Return the total number of voices in the project.

Performs a GET request to /voices/count.

Returns

GetVoicesCountResponse

Raises

SonioxAPIError When the API returns an error.

list_all()

list_all(limit: int = 100) -> AsyncGenerator[Voice, None]

Iterate through all cloned voices across all pages.

For the built-in voices of a model, use list_all_shared().

Parameters

Parameter	Type	Description
`limit`	`int`	Maximum number of voices to return.

Yields

AsyncGenerator[Voice, None]

Voice: The next voice object from the API.

Raises

SonioxAPIError When the API returns an error.

list_shared()

list_shared(model: str, *, gender: TtsVoiceGender | None = None, age: TtsVoiceAge | None = None, accent: str | None = None, use_case: list[str] | None = None, style: list[str] | None = None, limit: int = 100, cursor: str | None = None) -> GetSharedVoicesResponse

List the shared voices built into a Text-to-Speech model.

Performs a GET request to /shared-voices. All given filters must match. For voices you cloned yourself, use list().

Parameters

Parameter	Type	Description
`model`	`str`	Id of the TTS model whose voices to return.
`gender`	`TtsVoiceGender \| None`	Only return voices of this gender.
`age`	`TtsVoiceAge \| None`	Only return voices of this age.
`accent`	`str \| None`	Only return voices with this accent.
`use_case`	`list[str] \| None`	Only return voices tagged with every listed use case.
`style`	`list[str] \| None`	Only return voices tagged with every listed style.
`limit`	`int`	Maximum number of voices to return (1-200).
`cursor`	`str \| None`	Pagination cursor. Pass the same filters alongside it; the cursor points into the filtered list, not the whole catalogue.

Returns

GetSharedVoicesResponse

Raises

SonioxAPIError When the API returns an error.

list_all_shared()

list_all_shared(model: str, *, gender: TtsVoiceGender | None = None, age: TtsVoiceAge | None = None, accent: str | None = None, use_case: list[str] | None = None, style: list[str] | None = None, limit: int = 100) -> AsyncGenerator[TtsVoiceDetails, None]

Iterate through all shared voices of a Text-to-Speech model across all pages.

Accepts the same filters as list_shared(); they are sent with every page.

Parameters

Parameter	Type	Description
`model`	`str`	Id of the TTS model whose voices to return.
`gender`	`TtsVoiceGender \| None`	Only return voices of this gender.
`age`	`TtsVoiceAge \| None`	Only return voices of this age.
`accent`	`str \| None`	Only return voices with this accent.
`use_case`	`list[str] \| None`	Only return voices tagged with every listed use case.
`style`	`list[str] \| None`	Only return voices tagged with every listed style.
`limit`	`int`	Maximum number of voices to return.

Yields

AsyncGenerator[TtsVoiceDetails, None]

TtsVoiceDetails: The next voice matching the filters.

Raises

SonioxAPIError When the API returns an error.

get()

get(voice_id: str) -> Voice

Retrieve a voice by ID.

Performs a GET request to /voices/{voice_id}.

Parameters

Parameter	Type	Description
`voice_id`	`str`	Voice identifier.

Returns

Voice

Raises

SonioxAPIError When the API returns an error.

get_or_none()

get_or_none(voice_id: str) -> Voice | None

Retrieve a voice by ID.

Returns None if the voice does not exist.

Parameters

Parameter	Type	Description
`voice_id`	`str`	Voice identifier.

Returns

Voice | None

Raises

SonioxAPIError When the API returns an error.

create()

create(file: BinaryIO | bytes | Path | str, *, name: str, filename: str | None = None) -> Voice

Create a cloned voice from a reference audio clip.

Performs a multipart POST request to /voices.

Parameters

Parameter	Type	Description
`file`	`BinaryIO \| bytes \| Path \| str`	File input to upload or transcribe.
`name`	`str`	Name of the model.
`filename`	`str \| None`	Filename associated with uploaded file data.

Returns

Voice

Raises

SonioxAPIError When the API returns an error.

recompute()

recompute(voice_id: str, *, model: str | None = None) -> Voice

Prepare an existing voice for models it is not ready for yet.

Performs a POST request to /voices/{voice_id}/recompute. When model is omitted, the voice is prepared for every available model it is not ready for; models it is already prepared for are left unchanged.

Parameters

Parameter	Type	Description
`voice_id`	`str`	Voice identifier.
`model`	`str \| None`	Model to prepare the voice for. If None, prepares it for every not-yet-ready model.

Returns

Voice

Raises

SonioxAPIError When the API returns an error.

delete()

delete(voice_id: str) -> None

Delete a voice by ID.

Performs a DELETE request to /voices/{voice_id}.

Parameters

Parameter	Type	Description
`voice_id`	`str`	Voice identifier.

Returns

None

Raises

SonioxAPIError When the API returns an error.

delete_if_exists()

delete_if_exists(voice_id: str) -> None

Delete a voice by ID if it exists.

Ignores missing voices.

Parameters

Parameter	Type	Description
`voice_id`	`str`	Voice identifier.

Returns

None

Raises

SonioxAPIError When the API returns an error.

AsyncModelsAPI

Constructor

AsyncModelsAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

list()

list() -> GetModelsResponse

List available models.

Performs a GET request to /models.

Returns

GetModelsResponse

Raises

SonioxAPIError When the API returns an error.

AsyncUsageLogsAPI

Constructor

AsyncUsageLogsAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

list()

list(start_time: str, end_time: str, limit: int = 1000, sort: UsageLogsSort = 'end_time_asc', cursor: str | None = None) -> GetUsageLogsResponse

List usage-log entries for a time window.

Performs a GET request to /usage-logs.

Parameters

Parameter	Type	Description
`start_time`	`str`	Start of the window (inclusive). Filters by request end time.
`end_time`	`str`	End of the window (exclusive). Filters by request end time.
`limit`	`int`	Maximum number of entries to return (1–1000).
`sort`	`UsageLogsSort`	Sort order by end_time.
`cursor`	`str \| None`	Pagination cursor for the next page.

Returns

GetUsageLogsResponse

Raises

SonioxAPIError When the API returns an error.

list_all()

list_all(start_time: str, end_time: str, limit: int = 1000, sort: UsageLogsSort = 'end_time_asc') -> AsyncGenerator[UsageLogEntry, None]

Iterate through all usage-log entries across all pages.

Parameters

Parameter	Type	Description
`start_time`	`str`	Start of the window (inclusive). Filters by request end time.
`end_time`	`str`	End of the window (exclusive). Filters by request end time.
`limit`	`int`	Maximum number of entries to return (1–1000).
`sort`	`UsageLogsSort`	Sort order by end_time.

Returns

AsyncGenerator[UsageLogEntry, None]

AsyncUsageAPI

Constructor

AsyncUsageAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

summary()

summary(start_time: str, end_time: str) -> GetUsageSummaryResponse

Return daily cost and activity for the project, per model and in total.

Performs a GET request to /usage/summary.

Parameters

Parameter	Type	Description
`start_time`	`str`	Start of the window (inclusive), ISO 8601 UTC.
`end_time`	`str`	End of the window (exclusive), ISO 8601 UTC. A UTC day is included when the window covers any part of it, so an `end_time` at exactly midnight leaves out its own day. At most 366 days.

Returns

GetUsageSummaryResponse

Raises

SonioxAPIError When the API returns an error.

AsyncConcurrencyLimitsAPI

Constructor

AsyncConcurrencyLimitsAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

get()

get() -> GetConcurrencyLimitsResponse

Get current concurrent sessions and configured limits.

Performs a GET request to /concurrency-limits.

Returns

GetConcurrencyLimitsResponse

Project- and organization-scoped current counts and configured limits for realtime STT and TTS sessions.

Raises

SonioxAPIError When the API returns an error.

history()

history(start_time: str, end_time: str, *, period_sec: ConcurrentStreamsPeriodSec, kind: ConcurrentStreamKind) -> GetConcurrentStreamsHistoryResponse

Get historical concurrent stream counts, aggregated per period.

Performs a GET request to /concurrent-streams-history.

Parameters

Parameter	Type	Description
`start_time`	`str`	Start of the window (inclusive), ISO 8601 UTC.
`end_time`	`str`	End of the window (exclusive), ISO 8601 UTC, after `start_time`.
`period_sec`	`ConcurrentStreamsPeriodSec`	Aggregation period: 60, 3600, or 86400. Also caps the window length the server accepts (7 days for 60).
`kind`	`ConcurrentStreamKind`	`stt` for Speech-to-Text sessions, `tts` for Text-to-Speech.

Returns

GetConcurrentStreamsHistoryResponse

Raises

SonioxAPIError When the API returns an error.

AsyncAuthAPI

Constructor

AsyncAuthAPI(client: AsyncSonioxClient)

Parameters

Parameter	Type	Description
`client`	`AsyncSonioxClient`	Soniox client instance.

Returns

None

create_temporary_api_key()

create_temporary_api_key(*, usage_type: TemporaryApiKeyUsageType = 'transcribe_websocket', expires_in_seconds: int = 5 * 60, client_reference_id: str | None = None, single_use: bool | None = None, max_session_duration_seconds: int | None = None) -> CreateTemporaryApiKeyResponse

Create a temporary API key.

Performs a POST request to /auth/temporary-api-key.

The API key needs the Temporary API keys permission and the permission for the service in usage_type. See API key permissions.

Parameters

Parameter	Type	Description
`usage_type`	`TemporaryApiKeyUsageType`	Intended usage of the temporary API key.
`expires_in_seconds`	`int`	Duration in seconds until the temporary API key expires
`client_reference_id`	`str \| None`	Optional tracking identifier string. Does not need to be unique
`single_use`	`bool \| None`	When true, restricts the temporary API key to a single use.
`max_session_duration_seconds`	`int \| None`	Maximum connection duration in seconds for WebSocket and TTS HTTP streaming endpoints.

Returns

CreateTemporaryApiKeyResponse

Raises

SonioxPermissionDeniedError When the API key lacks one of those permissions.
SonioxAPIError When the API returns another error.

Async Client

On this page