> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about the Supertone API — keys, voices, credits, errors, and integrations.

## Getting started

> **Where do I get an API key?**
>
> Sign up for the [developer console](https://console.supertoneapi.com) and create a new key. You can issue up to **3 keys per account**, and revoke or reissue at any time.

> **How do I authenticate requests?**
>
> Include the header `x-sup-api-key: [YOUR_API_KEY]` on every request. Both SDKs accept the key via the constructor — see [Authentication](/en/docs/authentication).

> **Do I need a separate Play account?**
>
> No. The API and [Supertone Play](https://play.supertone.ai) share the same account, credit balance, and voice library.

> **Which SDKs are officially supported?**
>
> Two SDKs are official: [Python](/en/docs/developer-tools/python) (`supertone` on PyPI) and [TypeScript](/en/docs/developer-tools/typescript) (`@supertone/supertone` on npm). For other languages, call the [REST API](/en/api-reference/introduction) directly.

## Voices and TTS calls

> **How do I find a voice ID?**
>
> Three options: (1) copy from the voice card in [Supertone Play](https://play.supertone.ai), (2) call `GET /v1/voices`, or (3) filter with `GET /v1/voices/search`. See [Voices](/en/docs/core-concepts/voices).

> **Can I use cloned voices from Play in the API?**
>
> 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.

> **Why am I getting 403 on a voice that exists?**
>
> 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`.

> **What combinations of language/style/model does a voice support?**
>
> 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.

> **Is style required?**
>
> No. If you omit `style`, the first value in the voice's `styles` array is used as the default.

> **Can I tune pitch and speed?**
>
> Yes — see [Voice settings](/en/docs/text-to-speech/voice-settings). Different models support different parameters; unsupported settings are silently ignored.

> **How long can the text be?**
>
> The raw API caps `text` at **300 characters**. The Python and TypeScript SDKs auto-chunk longer text and merge the audio. See [Long text](/en/docs/text-to-speech/long-text).

> **What does `predict_duration` do?**
>
> 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](/en/docs/production/cost-and-usage#predict-duration).

## Credits and pricing

> **How is the API billed?**
>
> 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](https://play.supertone.ai/subscription).

> **How do I check my credit balance?**
>
> Two options: (1) call `GET /v1/credits` (or the SDK's `get_credit_balance`), or (2) view the dashboard in the console or Play.

> **Are credits shared between Play and the API?**
>
> Yes. The same balance applies to both. Cloned voice calls deduct credits the same way as preset voices.

## Errors and troubleshooting

> **What are the most common errors?**
>
> * **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](/en/docs/production/error-handling).

> **My calls keep failing — where do I look?**
>
> 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](/en/docs/resources/support) with the request body, headers, and the time the issue occurred.

> **What are the rate limits?**
>
> Defaults are 20 / 30 / 60 requests per minute by tier. Voice cloning is 10/minute. See [Rate limits](/en/docs/production/rate-limits).

## Operational

> **Can anyone use the API?**
>
> Yes — sign up in the console and you're ready to go. No approval gate.

> **Is there an enterprise plan?**
>
> Yes. For team-level usage, higher rate limits, sub-user accounts, or dedicated capacity, [submit an enterprise inquiry](https://docs.google.com/forms/d/1YexQpjpK0ZEou12blTytkZLqvrV-Uv95GbhxoOQ54R8/edit).

> **Where do I report bugs or get help?**
>
> Open a 1:1 inquiry through [customer support](https://support.supertone.ai/hc/en-us/categories/10267196754959-Play). Include request payload, headers, and timestamps for faster resolution.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.