Skip to main content

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.

​
Getting started

Sign up for the developer console and create a new key. You can issue up to 3 keys per account, and revoke or reissue at any time.
Include the header x-sup-api-key: [YOUR_API_KEY] on every request. Both SDKs accept the key via the constructor — see Authentication.
No. The API and Supertone Play share the same account, credit balance, and voice library.
Two SDKs are official: Python (supertone on PyPI) and TypeScript (@supertone/supertone on npm). For other languages, call the REST API directly.

​
Voices and TTS calls

Three options: (1) copy from the voice card in Supertone Play, (2) call GET /v1/voices, or (3) filter with GET /v1/voices/search. See Voices.
Yes. Voices cloned in Play are immediately available to the API on the same account. Likewise, voices you create via POST /v1/custom-voices/cloned-voice show up in Play. There’s no sync step.
Custom (cloned) voices can only be called by the account that created them. If you’re using a key from a different account, the API returns 403 Forbidden.
The samples field on the voice object lists every supported (language, style, model) tuple — including a preview URL for each. Check it before sending a TTS request.
No. If you omit style, the first value in the voice’s styles array is used as the default.
Yes — see Voice settings. Different models support different parameters; unsupported settings are silently ignored.
The raw API caps text at 300 characters. The Python and TypeScript SDKs auto-chunk longer text and merge the audio. See Long text.
It returns the predicted length of generated audio for a given text — without consuming credits. Useful for cost preview and UI hints. See Predict duration.

​
Credits and pricing

Credits are deducted per second of generated audio. Pricing uses the same credit system as Play; you can buy credits on the Play subscription page.
Two options: (1) call GET /v1/credits (or the SDK’s get_credit_balance), or (2) view the dashboard in the console or Play.
Yes. The same balance applies to both. Cloned voice calls deduct credits the same way as preset voices.

​
Errors and troubleshooting

  • 401 — missing or invalid API key
  • 402 — out of credits
  • 403 — voice not owned by this account
  • 400 — request body issue (missing field, invalid enum, text over 300 chars on raw API)
  • 429 — rate limit hit
Full reference: Error handling.
Check, in order:
  1. x-sup-api-key header is set with no leading/trailing whitespace.
  2. Content-Type: application/json on POST requests.
  3. voice_id is a real ID for your account (call GET /v1/voices or GET /v1/custom-voices).
  4. text, language, and style align with what the voice supports.
If problems persist, contact support with the request body, headers, and the time the issue occurred.
Defaults are 20 / 30 / 60 requests per minute by tier. Voice cloning is 10/minute. See Rate limits.

​
Operational

Yes — sign up in the console and you’re ready to go. No approval gate.
Yes. For team-level usage, higher rate limits, sub-user accounts, or dedicated capacity, submit an enterprise inquiry.
Open a 1:1 inquiry through customer support. Include request payload, headers, and timestamps for faster resolution.