The Supertone API ships with two officially supported SDKs. They wrap the REST API with idiomatic clients, handle streaming and long text for you, and stay in sync with the OpenAPI specification.Documentation Index
Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
Use this file to discover all available pages before exploring further.
Python SDK
pip install supertone — sync and async clients, parallel auto-chunking.TypeScript SDK
npm add @supertone/supertone — promise-based, ESM/CJS, Node and Bun.Package summary
| Python | TypeScript | |
|---|---|---|
| Package | supertone on PyPI | @supertone/supertone on npm |
| Repo | supertone-inc/supertone-python | supertone-inc/supertone-ts |
| Languages | Python 3.9+ | TypeScript 5+ / Node 18+ |
| Module formats | — | ESM + CommonJS |
| Auth | Supertone(api_key=...) | new Supertone({ apiKey: ... }) |
| Sync API | Yes (default) | n/a |
| Async API | *_async methods + async with | All methods (Promises) |
| Streaming | iter_bytes() / aiter_bytes() | ReadableStream reader |
| Auto-chunk long text | ✅ (300 chars, parallel up to 3 workers) | ✅ (300 chars, sequential) |
| Custom retries | ✅ via retry_config | ✅ via retryConfig |
| HTTP backend | httpx | fetch |
What the SDKs do for you
- Authentication — pass your API key once at construction; every request gets the right header.
- Type-safe enums for languages, models, and output formats.
- Streaming — iterate audio chunks idiomatically (Python generators, TS
ReadableStream). - Long-text auto-chunking — both SDKs split inputs at 300 characters, run TTS per chunk, and merge the audio. The streaming variants forward chunks transparently, so consumers don’t need to know that the underlying request was split.
- Errors — typed exception/error classes keyed to HTTP status codes (
UnauthorizedErrorResponse,TooManyRequestsErrorResponse, etc.). - Retry policy — configurable retries with backoff for transient
5xxand429responses.
When to use the REST API directly
The REST API is available for languages and runtimes where an SDK isn’t published — Go, Java, PHP, Rust, embedded systems — or when you want maximum control over the wire format. The endpoints are documented in the API Reference; examples in that section includecurl, JavaScript, Go, Python, PHP, and Java.
If you call REST directly, you’ll need to implement chunking, retries, and streaming consumption yourself.
Next
Python SDK
Install, authenticate, and run your first call.
TypeScript SDK
Install, authenticate, and run your first call.