soniox 2.3.2__tar.gz → 2.5.0__tar.gz

soniox-2.5.0/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(just test *)",
+      "Bash(/home/miha/workspace/soniox_python_sdk/.venv/bin/python *)",
+      "Bash(git apply *)",
+      "Bash(git add *)",
+      "Bash(sed -n '110,140p' tests/unit/test_client.py)",
+      "Bash(sed -n '85,120p' tests/unit/test_async_client.py)",
+      "Bash(/tmp/soniox-v240-test/.venv/bin/python -u test_schema_sync.py)",
+      "Bash(awk '/^class Transcription\\\\b/,/^class [A-Z]/' src/soniox/types/api.py)"
+    ]
+  }
+}

soniox-2.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug report
+description: Report something the SDK does wrong, or fails to do
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. A **minimal** reproducer speeds things up significantly.
+
+  - type: checkboxes
+    id: non_api
+    attributes:
+      label: SDK or API?
+      description: For API-level problems such as transcription accuracy or server-side errors, please contact [support@soniox.com](mailto:support@soniox.com) instead.
+      options:
+        - label: I confirm this is an issue with the Python SDK, not the Soniox API.
+          required: true
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened?
+      description: What did you observe? What did you expect instead?
+      placeholder: |
+        Observed: ...
+        Expected: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproducer
+      description: The smallest script that triggers the issue. Strip out anything unrelated.
+      render: python
+      placeholder: |
+        from soniox import SonioxClient
+        ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Logs or traceback
+      description: Full traceback or relevant log lines, if any.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: sdk_version
+    attributes:
+      label: SDK version
+      placeholder: "soniox==2.4.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "Python 3.12.3"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "Ubuntu 24.04 / macOS 15 / Windows 11"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Anything else relevant: timing patterns, frequency, workarounds you have tried.
+    validations:
+      required: false

soniox-2.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Propose a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template to propose new SDK functionality or improvements to existing APIs.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do? What does the SDK currently make hard or awkward?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: The shape of the API or behavior you would like. Python sketches welcome.
+      render: python
+      placeholder: |
+        # What the call site could look like:
+        client.foo.bar(...)
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about, and why you do not prefer them.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links to similar features in other SDKs, related issues, or use-case background.
+    validations:
+      required: false

soniox-2.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Summary
+
+<!-- One or two sentences. What does this PR do, and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Internal refactor
+- [ ] Documentation
+
+## How to test
+
+<!-- Steps a reviewer can run to verify the change. -->
+
+## Checklist
+
+- [ ] Tests added or updated under `tests/unit/` or `tests/realtime/`.
+- [ ] `just lint`, `just typecheck`, and `just test` all pass locally.
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated, if the change is user-visible.
+- [ ] Reference docs regenerated with `just docs`, if public APIs changed.
+- [ ] No leftover `print()` debug statements or commented-out code.
+
+## Related issues
+
+<!-- Closes #123, refs #456 -->

soniox-2.5.0/.gitignore

@@ -0,0 +1,15 @@
+dist
+build
+__pycache__
+generated-docs
+
+# Virtualenv
+.venv
+
+# Test / coverage artifacts
+.coverage
+.pytest_cache
+htmlcov
+
+# Local audio scratch
+*.wav

soniox-2.5.0/CHANGELOG.md

@@ -0,0 +1,203 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is inspired by Keep a Changelog and this project follows Semantic Versioning.
+
+## Quick Guide for Contributors
+
+- Every PR that changes behavior must update **[Unreleased]**.
+- Write from the **user’s perspective** (what changed for SDK users).
+- Keep entries short (one clear sentence).
+- Use the correct section: **Added**, **Changed**, **Fixed**, **Deprecated**, **Removed**, **Security**.
+- Avoid internal details or commit-style messages.
+
+**Release process (maintainers):**
+
+- Rename **[Unreleased]** → new version + date.
+- Add a fresh empty **[Unreleased]** section at the top.
+
+### Version Categories Guide
+
+Use the following categories when adding entries:
+
+- **Added** - new features or capabilities.
+- **Changed** - updates to existing functionality.
+- **Deprecated** - features that will be removed soon.
+- **Removed** - features removed in this version.
+- **Fixed** - bug fixes.
+- **Security** - vulnerability fixes.
+
+---
+
+### Writing Guidelines
+
+- Write entries from the **user's perspective**, not implementation details.
+  - ✅ "Added async file uploads"
+  - ❌ "Refactored upload handler"
+
+- Keep lines short and scannable.
+- Group related changes into one bullet when possible.
+- Avoid commit-message noise.
+- Every released version should have a date.
+
+---
+
+### Versioning Notes
+
+This project follows Semantic Versioning:
+
+- **MAJOR** version when you make incompatible API changes.
+- **MINOR** version when you add functionality in a backward-compatible manner.
+- **PATCH** version when you make backward-compatible bug fixes.
+
+Examples:
+
+- `1.0.0` - stable API
+- `1.1.0` - new features added
+- `1.1.1` - bug fixes only
+
+---
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Fixed
+
+### Removed
+
+---
+
+## [2.5.0] - 12 jun 2026
+
+### Added
+
+- `LanguageCode` type alias (`Annotated[str, Field(min_length=2, max_length=2)]`) representing an ISO 639-1 two-letter code. Now used by `TranslationConfig.target_language`, `language_a`, `language_b`, and by the `language_hints` lists on `CreateTranscriptionPayload`, `CreateTranscriptionConfig`, and `RealtimeSTTConfig`.
+- `SupportedLanguage` model (renamed from `Language`) describing a `{code, name}` language entry returned by `client.models.list()`.
+- `translate*` methods on the async and sync STT clients (`translate`, `translate_from_url`, `translate_from_file_id`, `translate_from_file`, `translate_and_wait`, `translate_and_wait_with_tokens`). Pass `to=` for one-way translation (optionally with `source=` as a strict language hint) or `between=("en", "fr")` for two-way; exactly one of `to` or `between` is required.
+- `connect_timeout_sec` parameter on the realtime `connect()` and `connect_multi_stream()` methods (STT and TTS, sync and async): maximum seconds to wait for the WebSocket handshake. Defaults to 10 seconds; must be greater than zero. ([#4](https://github.com/soniox/soniox-python/pull/4) by [@imcooder](https://github.com/imcooder))
+
+### Changed
+
+- Reorganized reference docs: `async_client.md` now documents only the async surface (the sync `SonioxClient` is a line-by-line mirror, called out in a preamble); `realtime_client.md` continues to cover both sync and async realtime clients.
+- Expanded the `output_file_for_audio_format` docstring with a proper `Args` block.
+- `language_hints` fields now validate each entry as a two-letter code; previously any string was accepted client-side.
+- Realtime WebSocket connection failures now raise `SonioxRealtimeError` (with message `"Connection timed out"` when the handshake times out) instead of propagating raw `websockets` exceptions. ([#4](https://github.com/soniox/soniox-python/pull/4) by [@imcooder](https://github.com/imcooder))
+- Default model for asynchronous transcriptions is now `stt-async-v5` (was `stt-async-v4`).
+
+### Deprecated
+
+- `Language` is a deprecated alias for `SupportedLanguage`. Update imports to `from soniox.types import SupportedLanguage`.
+
+### Fixed
+
+- Removed Sphinx `:meth:` directive leaks from realtime STT client docstrings; they were rendering as raw text in the generated markdown reference.
+- `AsyncRealtimeTTSClient.connect_multi_stream()` now validates that an API key is available, matching the sync `RealtimeTTSClient.connect_multi_stream()`; previously it silently constructed a connection with an empty key.
+
+---
+
+## [2.4.0] - 13 may 2026
+
+### Added
+
+- `client.files.count()` and `client.stt.count()` endpoints (and async variants) returning the total count of files and transcriptions.
+- `client.usage_logs.list()` and `list_all()` (and async variants) for retrieving per-request usage logs over a time window.
+- `client.concurrency_limits.get()` (and async variant) returning current and configured concurrency limits for realtime STT and TTS, scoped to project and organization.
+- `TtsVoice.description` and `TtsVoice.gender` (`"male" | "female" | "neutral"`) fields, exposing richer voice metadata from the server. Enables programmatic voice filtering.
+- `RealtimeSTTAudioFormat`, `RealtimeSTTHeaderFormat`, `RealtimeSTTRawFormat` literal types covering the 30 audio formats accepted by realtime STT.
+- `py.typed` marker (PEP 561): downstream type-checkers now consume the SDK's inline type annotations.
+- `StructuredContext.general` and `StructuredContext.translation_terms` now accept a plain dict in addition to the typed item lists.
+- `finalize: bool = True` keyword-only parameter on realtime STT `pause()` (sync and async). When `False`, pause without emitting a finalize.
+- `TtsModel.languages` field listing the languages supported by the model. Defaults to an empty list for backward compatibility with direct construction.
+- `Language` type exported from `soniox.types` (previously only reachable via `soniox.types.api`).
+- `ApiError.more_info` field - optional URL pointing to documentation for resolving an error.
+- `Model.supports_max_endpoint_delay` flag indicating whether a model supports the `max_endpoint_delay_ms` option.
+- Internal test suite (pytest + respx + polyfactory) covering REST, realtime websocket, schema drift, and sync/async parity. Not shipped to users; runnable via `just test`.
+
+### Changed
+
+- `RealtimeSTTConfig.audio_format` is now typed as a Literal union instead of bare `str`. Passing an unrecognized value raises at validation time instead of failing on the wire.
+- Raw realtime STT audio formats (`pcm_*`, `mulaw`, `alaw`) now require `sample_rate` and `num_channels` on `RealtimeSTTConfig`. Previously these were silently accepted client-side and rejected by the server.
+
+---
+
+## [2.3.2] - 4 may 2026
+
+### Added
+
+- `single_use` and `max_session_duration_seconds` parameters on `client.auth.create_temporary_api_key()` (and the async variant).
+- `tts_rt` value for `TemporaryApiKeyUsageType`, allowing temporary API keys to be scoped to realtime TTS.
+
+---
+
+## [2.3.1] - 29 apr 2026
+
+### Changed
+
+- Default TTS model is now `tts-rt-v1` (previously `tts-rt-v1-preview`).
+
+---
+
+## [2.3.0] - 22 apr 2026
+
+### Added
+
+- Text-to-Speech (TTS) support, available on both `SonioxClient` and `AsyncSonioxClient`.
+- REST TTS API via `client.tts`: `generate()` returns audio bytes, `generate_to_file()` writes audio to a path or file-like object. Configurable `voice`, `model`, `language`, `audio_format`, `sample_rate`, and `bitrate`.
+- TTS model listing via `client.tts_models.list()`.
+- Realtime TTS over websocket via `client.realtime.tts.connect(...)`: stream text in with `send_text_chunk` / `send_text_chunks` / `finish`, receive audio with `receive_audio_chunks` or raw events with `receive_events`, plus `cancel`, `pause`, `resume`, and `keep_alive`.
+- Multiplexed realtime TTS via `client.realtime.tts.connect_multi_stream()`: run multiple concurrent TTS streams over a single websocket connection using `open_stream`.
+- New TTS examples for sync and async clients (REST, realtime, and multiplexed realtime).
+- `tts_api_base_url` and `tts_websocket_base_url` client options for overriding TTS endpoints.
+
+---
+
+## [2.2.0] - 25 feb 2026
+
+### Added
+
+- max_endpoint_delay_ms parameter (v4 model only)
+- fin (<fin>) and end (<end>) constants
+- validation for TranslationConfig
+
+### Changed
+
+- Improved docs generating script
+
+---
+
+## [2.1.0] - 18 feb 2026
+
+### Added
+
+- pause and resume methods
+- destroy_all method (removes all transcriptions and all files)
+- send_bytes accepts finish parameter
+
+### Changed
+
+- renamed client.transcriptions to 'client.stt'
+- removed send\_ prefix from methods (i.e. send_keep_alive -> keep_alive)
+
+### Removed
+
+- keep alive helpers (use pause, resume, or manually send keepalive message)
+
+---
+
+## [2.0.0] - 3 feb 2026
+
+### Added
+
+- Initial public release of the Python SDK.
+- Core client implementation (sync and async).
+- Full support for REST API and websocket API
+
+### Removed
+
+- Old Soniox Python SDK (versions 1._._)

soniox-2.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+Behavior that contributes to a positive environment includes:
+
+- Using welcoming and inclusive language.
+- Respecting differing viewpoints and experiences.
+- Accepting constructive criticism gracefully.
+- Focusing on what is best for the community.
+- Showing empathy toward other community members.
+
+Unacceptable behavior includes:
+
+- Sexualized language or imagery, and unwelcome sexual attention or advances.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical or email address, without their explicit permission.
+- Other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This Code of Conduct applies on GitHub, Discord, and any other channel where someone is representing the project.
+
+## Reporting and enforcement
+
+Report incidents to [support@soniox.com](mailto:support@soniox.com). All reports are reviewed and investigated promptly and fairly. We respect the privacy of reporters.
+
+Maintainers are responsible for clarifying and enforcing these standards, and may take corrective action in response to behavior they consider inappropriate.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

soniox-2.5.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Contributions are welcome. PRs that are small, typed, and tested move through review fastest.
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+Install [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just), then:
+
+```bash
+git clone https://github.com/soniox/soniox-python
+cd soniox-python
+uv sync --extra dev
+```
+
+> Python 3.13.6 has a regression in the `ssl` module that hangs realtime WebSocket sessions ([CPython #137583](https://github.com/python/cpython/issues/137583)). For local development, use Python 3.10 through 3.12, or 3.13.5 / 3.13.7 and later.
+
+Day-to-day commands:
+
+```bash
+just test          # full test suite
+just lint          # ruff
+just typecheck     # pyright
+just docs          # regenerate docs/*.md from source
+```
+
+## Opening a pull request
+
+Open PRs against the `dev` branch. `main` tracks releases.
+
+Before you push:
+
+1. Keep the PR focused. One bug fix, one feature, or one refactor. Mixed PRs are slower to review.
+2. Add tests. New endpoints belong in `tests/unit/`; realtime helpers belong in `tests/realtime/`.
+3. Run `just lint`, `just typecheck`, and `just test`. All three must pass before review.
+4. Maintain coverage above the threshold set in `pyproject.toml`.
+5. Update the `[Unreleased]` section of `CHANGELOG.md` for any user-visible change. Categorize as Added, Changed, Fixed, or Removed.
+6. If you changed public APIs, regenerate the reference docs with `just docs`.
+
+To pick up a newer OpenAPI schema, run `just download-schema`. This pulls the latest `openapi.json` into `tests/data/`. The `test_schema_drift.py` suite then reports missing fields and changed signatures automatically.
+
+## Conventions
+
+- `ruff` handles formatting and lint rules; the configuration lives in `pyproject.toml`.
+- `pyright` runs in strict mode against `src/`. Tests have a narrower config in the same file.
+- Write docstrings in plain markdown with backticks for code references. Do not use Sphinx directives such as `:meth:` or `:param:`. They leak as raw text into the generated reference.
+- Write comments to explain why, not what. Well-named identifiers already say what the code does.
+
+## Reporting bugs
+
+File issues at [github.com/soniox/soniox-python/issues](https://github.com/soniox/soniox-python/issues) using the bug report template. Include the SDK version, the Python version, and a minimal reproducer.
+
+## Reporting security issues
+
+Do not file a public issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the channels we monitor.

{soniox-2.3.2 → soniox-2.5.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: soniox
-Version: 2.3.2
+Version: 2.5.0
 Summary: The official Python SDK for the Soniox API (STT, REST)
-Project-URL: Homepage, https://sonoix.com
+Project-URL: Homepage, https://soniox.com
 Project-URL: Documentation, https://soniox.com/docs
 Project-URL: Repository, https://github.com/soniox/soniox-python
 Author-email: Soniox <support@soniox.com>
@@ -31,13 +31,20 @@ Requires-Dist: pydantic>2
 Requires-Dist: websockets>11.0
 Provides-Extra: dev
 Requires-Dist: griffe>=1.15.0; extra == 'dev'
-Requires-Dist: pyright>=1.1.0; extra == 'dev'
+Requires-Dist: polyfactory>=2.15.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.409; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.1; extra == 'dev'
 Requires-Dist: ruff>=0.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Soniox Python SDK
 
 The SDK exposes two clients: `SonioxClient` (sync) and `AsyncSonioxClient` (async). Each client supports:
+
 - STT over REST (`client.stt`) and realtime WebSocket (`client.realtime.stt`)
 - TTS over REST (`client.tts`) and realtime WebSocket (`client.realtime.tts`)
 - auth, file uploads, model listing, webhooks, and typed request/response models
@@ -53,20 +60,23 @@ export SONIOX_API_KEY=<your-key>
 
 Get your API key from the [Soniox Console](https://console.soniox.com) and inject it once per shell session. Both clients read `SONIOX_API_KEY` by default, but you can override it per-client if needed.
 
+> **Avoid Python 3.13.6** - it has a regression in `ssl` that hangs realtime STT/TTS (CPython issue [#137583](https://github.com/python/cpython/issues/137583)). Use any other 3.10-3.13.x.
+
 ## Quick run (STT + TTS, REST + realtime)
 
-1. **REST STT transcription**: copy this snippet or run [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
+1. **REST STT transcription**: transcribe a local file end-to-end in one call. Full example: [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
 
 ```python
 from soniox import SonioxClient
 
 client = SonioxClient()
-transcription = client.stt.transcribe(
-    audio_url="https://soniox.com/media/examples/coffee_shop.mp3",
-    client_reference_id="docs-quick-start",
+transcript = client.stt.transcribe_and_wait_with_tokens(
+    file="path/to/audio.mp3",                # local file
+    # audio_url="https://example.com/audio.mp3",  # or remote URL
+    delete_after=True,                        # auto-cleanup file + transcription
 )
-client.stt.wait(transcription.id, timeout_sec=60)
-print(client.stt.get_transcript(transcription.id).text[:200])
+print(transcript.text)
+client.close()
 ```
 
 2. **REST TTS generation**: convert text to an audio file.
@@ -118,17 +128,19 @@ def realtime():
             non_final_tokens.clear()
 
 realtime()
+client.close()
 ```
 
 See [`examples/soniox_client/realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/realtime_example.py) for the full flow.
 
-4. **Realtime TTS streaming**: send text chunks and read generated audio chunks from the session.
+4. **Realtime TTS streaming**: send text chunks and write audio to a file as it arrives.
 
 ```python
 from uuid import uuid4
 
 from soniox import SonioxClient
 from soniox.types import RealtimeTTSConfig
+from soniox.utils import output_file_for_audio_format
 
 client = SonioxClient()
 config = RealtimeTTSConfig(
@@ -139,17 +151,18 @@ config = RealtimeTTSConfig(
     audio_format="wav",
 )
 
-audio_chunks: list[bytes] = []
-with client.realtime.tts.connect(config=config) as session:
-    session.keep_alive()
+output_file = output_file_for_audio_format("wav", "tts_realtime_output")
+bytes_written = 0
+with client.realtime.tts.connect(config=config) as session, output_file.open("wb") as f:
     session.send_text_chunks(
         ["Hello from realtime TTS. ", "This is the final chunk."],
         text_end=True,
     )
     for chunk in session.receive_audio_chunks():
-        audio_chunks.append(chunk)
+        f.write(chunk)
+        bytes_written += len(chunk)
 
-print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+print(f"Wrote {bytes_written} bytes to {output_file.resolve()}")
 ```
 
 Run the full example at [`examples/soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_realtime_example.py) or async version at [`examples/async_soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_realtime_example.py).

{soniox-2.3.2 → soniox-2.5.0}/README.md

@@ -1,6 +1,7 @@
 # Soniox Python SDK
 
 The SDK exposes two clients: `SonioxClient` (sync) and `AsyncSonioxClient` (async). Each client supports:
+
 - STT over REST (`client.stt`) and realtime WebSocket (`client.realtime.stt`)
 - TTS over REST (`client.tts`) and realtime WebSocket (`client.realtime.tts`)
 - auth, file uploads, model listing, webhooks, and typed request/response models
@@ -16,20 +17,23 @@ export SONIOX_API_KEY=<your-key>
 
 Get your API key from the [Soniox Console](https://console.soniox.com) and inject it once per shell session. Both clients read `SONIOX_API_KEY` by default, but you can override it per-client if needed.
 
+> **Avoid Python 3.13.6** - it has a regression in `ssl` that hangs realtime STT/TTS (CPython issue [#137583](https://github.com/python/cpython/issues/137583)). Use any other 3.10-3.13.x.
+
 ## Quick run (STT + TTS, REST + realtime)
 
-1. **REST STT transcription**: copy this snippet or run [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
+1. **REST STT transcription**: transcribe a local file end-to-end in one call. Full example: [`examples/soniox_client/api_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/api_example.py).
 
 ```python
 from soniox import SonioxClient
 
 client = SonioxClient()
-transcription = client.stt.transcribe(
-    audio_url="https://soniox.com/media/examples/coffee_shop.mp3",
-    client_reference_id="docs-quick-start",
+transcript = client.stt.transcribe_and_wait_with_tokens(
+    file="path/to/audio.mp3",                # local file
+    # audio_url="https://example.com/audio.mp3",  # or remote URL
+    delete_after=True,                        # auto-cleanup file + transcription
 )
-client.stt.wait(transcription.id, timeout_sec=60)
-print(client.stt.get_transcript(transcription.id).text[:200])
+print(transcript.text)
+client.close()
 ```
 
 2. **REST TTS generation**: convert text to an audio file.
@@ -81,17 +85,19 @@ def realtime():
             non_final_tokens.clear()
 
 realtime()
+client.close()
 ```
 
 See [`examples/soniox_client/realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/realtime_example.py) for the full flow.
 
-4. **Realtime TTS streaming**: send text chunks and read generated audio chunks from the session.
+4. **Realtime TTS streaming**: send text chunks and write audio to a file as it arrives.
 
 ```python
 from uuid import uuid4
 
 from soniox import SonioxClient
 from soniox.types import RealtimeTTSConfig
+from soniox.utils import output_file_for_audio_format
 
 client = SonioxClient()
 config = RealtimeTTSConfig(
@@ -102,17 +108,18 @@ config = RealtimeTTSConfig(
     audio_format="wav",
 )
 
-audio_chunks: list[bytes] = []
-with client.realtime.tts.connect(config=config) as session:
-    session.keep_alive()
+output_file = output_file_for_audio_format("wav", "tts_realtime_output")
+bytes_written = 0
+with client.realtime.tts.connect(config=config) as session, output_file.open("wb") as f:
     session.send_text_chunks(
         ["Hello from realtime TTS. ", "This is the final chunk."],
         text_end=True,
     )
     for chunk in session.receive_audio_chunks():
-        audio_chunks.append(chunk)
+        f.write(chunk)
+        bytes_written += len(chunk)
 
-print(f"Collected {sum(len(c) for c in audio_chunks)} bytes of audio")
+print(f"Wrote {bytes_written} bytes to {output_file.resolve()}")
 ```
 
 Run the full example at [`examples/soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/soniox_client/tts_realtime_example.py) or async version at [`examples/async_soniox_client/tts_realtime_example.py`](https://github.com/soniox/soniox-python/blob/main/examples/async_soniox_client/tts_realtime_example.py).