Install & Compatibility
Where this runs
tested against v2.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.778s · 33.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.3s · import 0.722s · 33MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
breakingVersion 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]fixUpgrade 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]
affects: <2.0.0
breakingThe minimum required Python version was updated from `3.6` (for 1.x) to `3.10` (for 2.x). [2, 8, 13]fixEnsure your environment runs Python 3.10 or newer before upgrading to Soniox SDK v2.x. [2]
affects: <2.0.0
gotchaReal-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]fixImplement error detection for 503 errors (`Cannot continue request`) and logic to immediately restart the real-time session to continue streaming. [10]
affects: All
deprecatedSoniox 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]fixUsers are advised to check the Soniox console for current pricing and credit policies. Existing free credits may be phased out. [9]
affects: All new users (Feb 2026 onwards)
Errors
Common errors & fixes
soniox.exceptions.SonioxAPIError: When the API returns an error.
A problem occurred on the Soniox API server or your request was malformed/unauthorized.
fixInspect 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`.
The `client.stt.wait()` method timed out before the transcription could complete.
fixIncrease 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.
The parameters provided in your API request (e.g., `transcribe` method) did not conform to the expected schema.
fixCarefully 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.
A real-time WebSocket session was unexpectedly terminated by the Soniox service.
fixCatch this specific error in your real-time processing loop and implement logic to reconnect and restart the streaming process immediately. [10]
Upgrade
Version history
2.5.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
pythonrequiredRequired Python version for SDK functionality.