> ## 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.

# FAQ

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

## Getting started

<Accordion title="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.
</Accordion>

<Accordion title="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).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Voices and TTS calls

<Accordion title="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).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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`.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="Is style required?">
  No. If you omit `style`, the first value in the voice's `styles` array is used as the default.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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).
</Accordion>

<Accordion title="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).
</Accordion>

## Credits and pricing

<Accordion title="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).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Errors and troubleshooting

<Accordion title="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).
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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).
</Accordion>

## Operational

<Accordion title="Can anyone use the API?">
  Yes — sign up in the console and you're ready to go. No approval gate.
</Accordion>

<Accordion title="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).
</Accordion>

<Accordion title="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.
</Accordion>