Soniox Python SDK

2.2.0 · active · verified Thu Apr 16

The official Python SDK for the Soniox API, providing fully typed access to Async and Real-time Speech-to-Text (STT) capabilities. It simplifies integration by handling authentication, file uploads, transcription polling, and real-time stream helpers. The library is actively maintained with frequent updates, aiming to be a developer-friendly ecosystem for voice AI. [2, 3]

Common errors

```
soniox.exceptions.SonioxAPIError: When the API returns an error.
```
cause A problem occurred on the Soniox API server or your request was malformed/unauthorized.

fix Inspect the full error message for details (e.g., status code, specific message). Verify your API key, request parameters, and network connectivity. [4]
```
soniox.exceptions.TimeoutError: Waiting for the transcription to finish exceeded `timeout_sec`.
```
cause The `client.stt.wait()` method timed out before the transcription could complete.

fix Increase the `timeout_sec` parameter in the `wait()` call, especially for longer audio files. Ensure the audio URL is accessible and the file is not excessively large. [4]
```
soniox.exceptions.SonioxValidationError: When the payload fails validation.
```
cause The parameters provided in your API request (e.g., `transcribe` method) did not conform to the expected schema.

fix Carefully review the arguments passed to the SDK methods against the official documentation to ensure they match expected types and formats. [4]
```
Connection to wss://stt-rt.soniox.com/transcribe-websocket failed: 503 Cannot continue request (code N). Please restart the request.
```
cause A real-time WebSocket session was unexpectedly terminated by the Soniox service.

fix Catch this specific error in your real-time processing loop and implement logic to reconnect and restart the streaming process immediately. [10]

Warnings

breaking Version 2.x of the Soniox Python SDK introduced significant architectural changes and new import paths compared to 1.x, alongside an updated Python requirement. [3, 9]
Fix: Upgrade to Python 3.10+ and refer to the latest documentation for `SonioxClient` and `AsyncSonioxClient` initialization and API calls. Review your imports and method calls as they may have changed. [2, 8]
breaking The minimum required Python version was updated from `3.6` (for 1.x) to `3.10` (for 2.x). [2, 8, 13]
Fix: Ensure your environment runs Python 3.10 or newer before upgrading to Soniox SDK v2.x. [2]
gotcha Real-time transcription sessions may terminate early (e.g., due to network issues or API limits), returning a 503 error. Your application must handle these gracefully. [10]
Fix: Implement error detection for 503 errors (`Cannot continue request`) and logic to immediately restart the real-time session to continue streaming. [10]
deprecated Soniox has discontinued free API credits for new sign-ups due to widespread abuse. Existing free credits may still be valid but check your console. [9]
Fix: Users are advised to check the Soniox console for current pricing and credit policies. Existing free credits may be phased out. [9]

Install

pip install soniox Install stable version

Imports

SonioxClient
```
from soniox import SonioxClient
```
Main synchronous client for REST API interactions.
AsyncSonioxClient
```
from soniox import AsyncSonioxClient
```
Main asynchronous client for REST API interactions.
RealtimeSTTConfig
```
from soniox.types import RealtimeSTTConfig
```
Configuration object for real-time STT sessions.
Token
```
from soniox.types import Token
```
Represents a transcribed word or subword token from real-time STT.
render_tokens
```
from soniox.utils import render_tokens
```
Utility for rendering real-time transcription tokens.

Quickstart

This quickstart demonstrates how to initialize the synchronous `SonioxClient`, transcribe an audio file from a public URL, wait for its completion, retrieve the transcript, and then delete the transcription. It uses the `SONIOX_API_KEY` environment variable for authentication. [1, 2]

import os
from soniox import SonioxClient

# Get your API key from https://console.soniox.com/api-keys
# It's recommended to set SONIOX_API_KEY as an environment variable.
soniox_api_key = os.environ.get('SONIOX_API_KEY', 'YOUR_SONIOX_API_KEY')

if not soniox_api_key or soniox_api_key == 'YOUR_SONIOX_API_KEY':
    print("Error: SONIOX_API_KEY environment variable not set or placeholder used.")
    print("Please set it to your actual Soniox API key.")
else:
    try:
        client = SonioxClient(api_key=soniox_api_key)

        # Example: Transcribe an audio file from a public URL asynchronously
        print("Starting transcription...")
        transcription = client.stt.transcribe(
            audio_url="https://soniox.com/media/examples/coffee_shop.mp3"
        )

        print(f"Transcription ID: {transcription.id}")
        print("Waiting for transcription to complete...")
        client.stt.wait(transcription.id, timeout_sec=120)

        transcript = client.stt.get_transcript(transcription.id)
        print("\nTranscription complete:")
        print(transcript.text)

        # Optionally delete the transcription and associated file to save resources
        client.stt.delete(transcription.id)
        print(f"Transcription {transcription.id} and associated file deleted.")

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →