Frequently asked questions
How do I generate an API key?
Sign up on the /get-api-key/ page using Google or an email and password. The dashboard displays your active API key, balance, and usage statistics. Each account holds one active key at a time, which you can manage directly from this interface.
What is the base URL for the API?
The API base URL is https://api.playkuwi.com/v1. You send POST requests to https://api.playkuwi.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available under this base URL structure.
Can I use the OpenAI SDK with Kuwi?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.playkuwi.com/v1 and using your site-specific key. The request shape matches the OpenAI speech endpoint, allowing seamless integration without custom client code.
What is the maximum character limit per request?
Each request supports up to 4096 characters in the input field. For longer scripts, split the text into chunks of this size and join the resulting audio files. Spaces and punctuation count toward this limit.
How do I change the speed of the audio?
Include a speed parameter in your request body, accepting values between 0.25 and 4.0. This adjusts the playback rate of the generated audio file.
Which voices support all 23 languages?
All eight voice presets support every one of the 23 supported languages. You can assign any voice to any language, including English, Spanish, Japanese, or Swahili, without restriction. The language is either guessed or explicitly set.
Is the API key unique per account?
Yes, each account maintains one active API key. You can issue a new key at any time, which immediately invalidates the previous one. This ensures a single active credential per account for security and simplicity.
How do I handle rate limit errors?
The limit is 60 requests per minute per key (10 before the first top-up). Implement exponential backoff or queueing in your application logic. Requests are processed sequentially, so delays may occur under load or during high usage.
What happens if the synthesis fails?
Failed requests are free, and the charge is returned in full. You will receive an error response indicating the failure. Simply retry the request or adjust parameters like input text or voice selection as needed.
Can I specify a language code?
Yes, include an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the code ensures accuracy for non-English content.
Are there any SSML tags supported?
No, the API does not support SSML tags. It accepts plain text input up to 4096 characters. Audio generation relies solely on the provided text and voice selection.
How do I get a list of available voices?
Send a GET request to /v1/voices. This endpoint returns details about available voices, languages, and formats. You can also check /v1/models for model-specific information. Use this data to select the appropriate voice for your content.
Is streaming audio supported?
No, streaming or WebSocket support is not available. The API returns the complete audio file in the response body. You receive the full MP3, WAV, OPUS, FLAC, or PCM file after synthesis completes, rather than partial chunks.
How do I rotate my API key?
Issue a new key from the /get-api-key/ dashboard page. The old key stops working immediately upon issuing the new one. This ensures seamless rotation without downtime, as only one key is active per account at any time.
First request
curl
curl https://api.playkuwi.com/v1/audio/speech \
-H "Authorization: Bearer $TTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
--output hello.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.playkuwi.com/v1", api_key="tts-...")
with client.audio.speech.with_streaming_response.create(
model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
response.stream_to_file("hello.mp3")Node.js (openai)
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.playkuwi.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));| voice | |
|---|---|
aria | female |
nova | female |
luna | female |
sage | female |
felix | male |
milo | male |
atlas | male |
orion | male |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
Authentication
Access the Kuwi API by generating a unique key from your account dashboard at /get-api-key/. Each account is issued one active key, which must be included in every request header for authentication.
API Key Generation
Sign in with Google or email to retrieve your key. The dashboard displays your current key, balance, and usage statistics immediately upon login.
Bearer Token Usage
Include your key in the HTTP header as Authorization: Bearer tts-.... The official OpenAI SDKs work seamlessly by pointing to https://api.playkuwi.com/v1.
Key Rotation Policy
You can issue a new key at any time from your dashboard. The previous key stops working immediately upon generation, ensuring secure access control.
Speech Endpoint
The core integration point is the POST /v1/audio/speech endpoint, accepting JSON payloads to synthesize text into audio. This endpoint mirrors the OpenAI speech structure, allowing direct use of standard SDKs by adjusting the base URL to https://api.playkuwi.com/v1.
POST /v1/audio/speech
Send a POST request to https://api.playkuwi.com/v1/audio/speech. The request body must include the model, input text, voice preset, and response_format. Optional parameters include speed (0.25–4.0) and language (ISO code).
Request Body Parameters
Key fields include model ("tts-1" or "tts-1-hd"), input (max 4096 characters), and voice (e.g., "aria", "atlas"). The input text is charged per character, including spaces. If language is omitted, the system guesses it from the script, defaulting to English for Latin text.
- Model: "tts-1" or "tts-1-hd"
- Input: String, max 4096 chars
- Voice: One of 8 presets
- Speed: 0.25 to 4.0
- Response Format: mp3, wav, opus, flac, pcm
Response Format
The endpoint returns the generated audio file in the response body. The content type matches the requested response_format. Failed requests return an error JSON object and incur no charge.
Voice and Model Options
Kuwi Audio provides eight distinct voice presets optimized for podcast production, ranging from warm narrators to energetic promo styles. Each voice is derived from licensed recordings, ensuring consistent broadcast quality across all episodic content.
Available Voices List
The API offers eight presets: Aria, Nova, Luna, and Sage for female voices; Felix, Milo, Atlas, and Orion for male voices. Select the voice that best matches your podcast’s tone, from soft storytelling to neutral news delivery.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
- Atlas: Neutral, news
- Orion: Deep, documentary
Model Selection
Choose between tts-1 and tts-1-hd. Both models use the same underlying engine and incur identical pricing. Select tts-1-hd if your podcast requires higher fidelity, though the audio quality difference is subtle for standard broadcast use.
Speed Adjustments
Adjust the speed parameter between 0.25 and 4.0 to control playback rate. This allows you to tighten pacing for fast-paced segments or slow down complex explanations without re-recording the entire script.
Supported Formats
The API returns audio in five standardized formats, allowing podcast publishers to select the optimal balance between file size and fidelity for their distribution pipeline. Each format is generated by the same underlying engine, ensuring consistent voice quality regardless of the container choice.
MP3 Output
MP3 is the default and most widely supported format for podcast platforms. It offers efficient compression for streaming and downloading, making it ideal for standard episodic content distribution where moderate file sizes are preferred.
WAV and FLAC Quality
WAV provides uncompressed PCM audio, ensuring lossless fidelity for archiving or further editing. FLAC offers lossless compression while preserving exact audio quality. Both are suitable for high-quality master files.
Opus and PCM Options
Opus provides excellent quality at low bitrates, ideal for efficient web delivery. PCM returns raw uncompressed audio data, useful for custom processing pipelines. All formats support the same speed and voice parameters, allowing flexible post-production workflows.
Rate Limits
Kuwi Audio enforces a strict rate limit of 60 requests per minute per API key. This ceiling ensures consistent synthesis quality for podcast publishers generating episodic content at scale. Since requests are processed sequentially, high-volume batches may experience slight queuing delays during peak usage.
60 Requests Per Minute
Each active API key supports up to 60 requests per minute. This limit applies regardless of text length, as each call consumes one unit of the quota. Publishers should account for this concurrency cap when automating batch exports of multiple episodes.
Initial Limit for New Accounts
New accounts start with a reduced limit of 10 requests per minute. This restriction remains in effect until the first top-up is processed. Once a minimum $5 USDT transfer is confirmed on the TRON network, the rate limit automatically increases to the standard 60 requests per minute.
Handling 429 Errors
When the limit is exceeded, the API returns a 429 Too Many Requests status code. Implement exponential backoff in your integration to retry after a short delay. Failed requests are free, so throttled attempts incur no cost.
- Retry logic should account for sequential processing queues.

Error Codes
Errors follow standard HTTP conventions, allowing your podcast automation pipelines to handle failures gracefully without manual intervention. The API returns specific codes for common issues, ensuring you can debug integration problems quickly.
Invalid API Key
Returns a 401 status if the Bearer token is missing, malformed, or revoked. Since a new key instantly invalidates the old one, ensure your scripts use the latest key from the dashboard.
- Check for typos in the
Authorization: Bearer tts-...header. - Regenerate via /get-api-key/ if the old key no longer works.
Input Too Long
Returns a 400 status if the input field exceeds 4096 characters. Your client code should split long scripts into chunks, synthesize them individually, and join the audio files before delivery.
- Split text at natural sentence boundaries before 4096 chars.
- Concatenate resulting audio files on the server side.
Server Errors
A 500 error indicates a temporary synthesis failure. Failed requests are free, so you can safely retry with exponential backoff. Persistent errors may require checking the /v1/models endpoint.
- Implement retry logic with jitter.
- Verify balance and rate limits if retries fail repeatedly.
Code Examples
The API follows the OpenAI request shape, allowing immediate integration with existing client libraries. You can generate audio files by sending a POST request to the speech endpoint with your model, voice, and input text.
Below are minimal examples for generating speech in Python and Node.js. Replace YOUR_API_KEY with your key from the dashboard. Ensure your base URL points to https://api.playkuwi.com/v1.
cURL Command
Use this command to generate a quick audio clip. It requests the nova voice in English, outputting an MP3 file named output.mp3. Ensure you replace the placeholder key with your actual credential.
```bash curl -X POST https://api.playkuwi.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello from Kuwi Audio", "voice": "nova", "response_format": "mp3"}' \ -o output.mp3 ```
Python OpenAI SDK
Install the official OpenAI SDK and configure the base URL to point to our API. This allows you to use standard methods like audio.speech.create() while leveraging your Kuwi key.
```python import openai client = openai.OpenAI(api_key="YOUR_API_KEY", base_url="https://api.playkuwi.com/v1") speech_file = client.audio.speech.create( model="tts-1", voice="nova", input="Your script text here" ) speech_file.stream_to_file("output.mp3") ```
Node.js Implementation
For Node.js environments, use the openai npm package. Set the baseURL to our API endpoint to ensure requests are routed correctly. The response_format defaults to mp3.
```javascript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://api.playkuwi.com/v1' }); const response = await client.audio.speech.create({ model: 'tts-1', voice: 'nova', input: 'Your script text here', response_format: 'mp3' }); await response.arrayBuffer(); ```
Language Handling
Kuwi Audio’s API automatically detects language from the input script’s Unicode characters. Latin script defaults to English; other scripts trigger their respective languages. This simplifies integration when processing standard text inputs.
Auto-Detection Logic
The system infers language from character scripts. Latin characters default to English. Non-Latin scripts trigger their native language models. This reduces the need for manual configuration in simple workflows.
Explicit Language Codes
For non-English Latin text, set the language parameter to the ISO code. This prevents misidentification. Supported ISO codes cover all 23 languages, including Arabic, Chinese, Japanese, and Swahili.
- Set
languagefor ambiguous Latin text (e.g., Spanish vs. English). - Supported codes apply to all 8 voices.
- Optional parameter; defaults to English for Latin script.
Unsupported Languages
The API does not support Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, or Bengali. Using unsupported languages may result in default English synthesis or errors. Check the 23 supported languages before integration.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
