Kuwi Text-to-Speech API Documentation and Integration Guide

By Kuwi Audio editorial team · Updated 2026-11-18

This guide details the integration steps for Kuwi Audio’s text-to-speech API, designed specifically for podcast publishers and developers converting scripts into broadcast-quality audio. You will find precise specifications for the POST /v1/audio/speech endpoint, including required request bodies, supported response formats, and authentication methods. The documentation covers all eight voice presets, model selection between tts-1 and tts-1-hd, and rate limit constraints to help you build reliable episodic content production pipelines.

Start by generating your API key via the /get-api-key/ dashboard, then use standard OpenAI SDKs by pointing them to https://api.playkuwi.com/v1. We provide concrete code examples in cURL, Python, and Node.js to demonstrate quick integration using the official OpenAI SDKs. Review the supported languages, character limits, and pricing structure to ensure your workflow handles up to 4096 characters per request efficiently. This reference material contains only verified technical facts to streamline your development process without unnecessary complexity.

Kuwi Text-to-Speech API Documentation and Integration Guide

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

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: 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

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

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.
Rate Limits

Error Codes

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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 language for 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. Node.js documentation
  3. OpenAI API reference: create speech
  4. curl documentation
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. Python documentation
  8. openai-python on GitHub
  9. LibriTTS-R corpus (OpenSLR 141)
  10. LibriVox public-domain audiobooks
  11. Creative Commons Attribution 4.0
  12. FFmpeg documentation

More on this site