{"id":7734,"library":"soniox","title":"Soniox Python SDK","description":"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]","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/soniox/soniox-python","tags":["speech-to-text","stt","ai","api-client","audio","real-time","async"],"install":[{"cmd":"pip install soniox","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version for SDK functionality.","package":"python","optional":false}],"imports":[{"note":"Main synchronous client for REST API interactions.","symbol":"SonioxClient","correct":"from soniox import SonioxClient"},{"note":"Main asynchronous client for REST API interactions.","symbol":"AsyncSonioxClient","correct":"from soniox import AsyncSonioxClient"},{"note":"Configuration object for real-time STT sessions.","symbol":"RealtimeSTTConfig","correct":"from soniox.types import RealtimeSTTConfig"},{"note":"Represents a transcribed word or subword token from real-time STT.","symbol":"Token","correct":"from soniox.types import Token"},{"note":"Utility for rendering real-time transcription tokens.","symbol":"render_tokens","correct":"from soniox.utils import render_tokens"}],"quickstart":{"code":"import os\nfrom soniox import SonioxClient\n\n# Get your API key from https://console.soniox.com/api-keys\n# It's recommended to set SONIOX_API_KEY as an environment variable.\nsoniox_api_key = os.environ.get('SONIOX_API_KEY', 'YOUR_SONIOX_API_KEY')\n\nif not soniox_api_key or soniox_api_key == 'YOUR_SONIOX_API_KEY':\n    print(\"Error: SONIOX_API_KEY environment variable not set or placeholder used.\")\n    print(\"Please set it to your actual Soniox API key.\")\nelse:\n    try:\n        client = SonioxClient(api_key=soniox_api_key)\n\n        # Example: Transcribe an audio file from a public URL asynchronously\n        print(\"Starting transcription...\")\n        transcription = client.stt.transcribe(\n            audio_url=\"https://soniox.com/media/examples/coffee_shop.mp3\"\n        )\n\n        print(f\"Transcription ID: {transcription.id}\")\n        print(\"Waiting for transcription to complete...\")\n        client.stt.wait(transcription.id, timeout_sec=120)\n\n        transcript = client.stt.get_transcript(transcription.id)\n        print(\"\\nTranscription complete:\")\n        print(transcript.text)\n\n        # Optionally delete the transcription and associated file to save resources\n        client.stt.delete(transcription.id)\n        print(f\"Transcription {transcription.id} and associated file deleted.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n","lang":"python","description":"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]"},"warnings":[{"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]","message":"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]","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Ensure your environment runs Python 3.10 or newer before upgrading to Soniox SDK v2.x. [2]","message":"The minimum required Python version was updated from `3.6` (for 1.x) to `3.10` (for 2.x). [2, 8, 13]","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Implement error detection for 503 errors (`Cannot continue request`) and logic to immediately restart the real-time session to continue streaming. [10]","message":"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]","severity":"gotcha","affected_versions":"All"},{"fix":"Users are advised to check the Soniox console for current pricing and credit policies. Existing free credits may be phased out. [9]","message":"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]","severity":"deprecated","affected_versions":"All new users (Feb 2026 onwards)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Inspect the full error message for details (e.g., status code, specific message). Verify your API key, request parameters, and network connectivity. [4]","cause":"A problem occurred on the Soniox API server or your request was malformed/unauthorized.","error":"soniox.exceptions.SonioxAPIError: When the API returns an error."},{"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]","cause":"The `client.stt.wait()` method timed out before the transcription could complete.","error":"soniox.exceptions.TimeoutError: Waiting for the transcription to finish exceeded `timeout_sec`."},{"fix":"Carefully review the arguments passed to the SDK methods against the official documentation to ensure they match expected types and formats. [4]","cause":"The parameters provided in your API request (e.g., `transcribe` method) did not conform to the expected schema.","error":"soniox.exceptions.SonioxValidationError: When the payload fails validation."},{"fix":"Catch this specific error in your real-time processing loop and implement logic to reconnect and restart the streaming process immediately. [10]","cause":"A real-time WebSocket session was unexpectedly terminated by the Soniox service.","error":"Connection to wss://stt-rt.soniox.com/transcribe-websocket failed: 503 Cannot continue request (code N). Please restart the request."}]}