Frequently asked questions
What SDKs are supported?
We do not provide an official SDK of our own. You can use the OpenAI SDK or plain HTTP requests. The OpenAI SDKs work by changing the base URL to our API endpoint. This allows you to use familiar libraries and code structures without needing a custom client.
Can I use the OpenAI SDK with this API?
Yes, the official OpenAI SDKs work with our API. You simply need to change the base URL to https://api.playli789.com/v1 and use your site-specific key. This compatibility allows you to use the same request shape as the OpenAI speech endpoint for seamless integration.
How do I set the base URL?
Set your base URL to https://api.playli789.com/v1. This endpoint handles POST requests for audio generation and GET requests for voices and models. Ensure your Authorization header includes your Bearer token starting with 'tts-...' to authenticate your requests correctly.
What is the maximum text length per request?
The maximum input text length is 4096 characters per request. If your script exceeds this limit, you must split the text into parts of up to 4096 characters. You then generate audio for each part and join the resulting audio files together.
How do I handle texts longer than 4096 characters?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate request to the speech endpoint. Once you receive the audio files for all parts, join them sequentially. This ensures the entire script is converted without hitting the character limit.
What format is returned by default?
The API returns audio in the format you specify in the request. Supported formats include mp3, wav, opus, flac, and pcm. If you do not specify a format, the API uses mp3 by default, but it is best practice to explicitly define your preferred output format.
How do I specify a language?
Include the optional 'language' field with an ISO code in your request body. If omitted, the API guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language field to ensure correct voice synthesis.
Does the API support streaming audio?
No, the API does not support streaming, WebSocket, or real-time partial audio. You send a request and receive the complete audio file in the response. This synchronous approach is suitable for generating full episodes or ads where immediate streaming is not required.
What happens if the API is slow?
Requests are processed one after another, so under load a request may wait in a queue. Typical speed is roughly real time, but short phrases take a few seconds. If the API is busy, your request will simply wait until it is processed.
Can I use custom speeds?
Yes, you can adjust the speed between 0.25 and 4.0. This allows you to speed up narration for ads or slow it down for detailed explanations. The speed parameter is included in the JSON body of your POST request to the speech endpoint.
How do I detect errors in the response?
Check the HTTP status code and response body for error details. Failed requests are free, and the charge is returned in full if synthesis fails. Inspect the response for specific error messages to understand why a request failed, such as invalid parameters or rate limits.
Is there a webhook for completion?
No, there is no webhook for completion. The API is synchronous, meaning you receive the audio file directly in the response. You do not need to set up a webhook to know when generation is complete, as the response contains the final audio data.
How do I rotate my API key?
You can issue a new API key at any time from your account dashboard. When a new key is issued, the old one stops working immediately. This ensures that only your current active key is used for authentication, maintaining security for your podcast production workflow.
What is the character limit for the free trial?
The free trial provides $0.50 of credit, which equals about 50,000 characters. This credit is valid for 7 days when you sign in with Google. Accounts created with email and password start without this trial credit, so consider using Google for the initial trial.
First request
curl
curl https://api.playli789.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.playli789.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.playli789.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
Secure your podcast narration workflow by authenticating requests with a unique API key. This key links your generation requests to your account balance, ensuring accurate billing for every character synthesized.
API Key Usage
Obtain your key on the /get-api-key/ page. Use it for all API calls to distinguish your voice generations from other users.
Header Format
Include the key in the HTTP header as Authorization: Bearer tts-.... Ensure no extra spaces are included in the token string.
Key Rotation
Generate a new key anytime via your dashboard. The previous key becomes invalid immediately, providing instant security if your key is exposed.
Endpoint Overview
Our API exposes three primary endpoints for generating and managing podcast audio assets. The core speech endpoint accepts text and parameters to return audio files, while the voices and models endpoints provide metadata about available synthesis options.
Speech Endpoint
Send a POST request to /v1/audio/speech with your JSON payload to generate audio. This is the primary interaction point where you define the model, input text, voice, and output format. The endpoint returns the audio file directly in the response body.
Voices Endpoint
Query GET /v1/voices to retrieve a list of all available voice presets, their associated languages, supported formats, and pricing details. This allows you to dynamically update your podcast interface with the latest voice options without hardcoding values.
Models Endpoint
Use GET /v1/models to verify the available model IDs, such as tts-1 and tts-1-hd. Both models use the same underlying engine and price, but this endpoint confirms the current configuration for your integration.

Request Parameters
Configure your speech generation by defining the text content, selecting a voice preset, and adjusting the playback speed. Each request processes up to 4,096 characters, so longer scripts should be split before submission.
Input Text
Provide the script text in the input field. Spaces and punctuation count toward the 4,096 character limit per request.
Voice Selection
Choose from eight presets like aria for narration or atlas for news. Every voice supports all 23 languages; if the language field is omitted, the system guesses based on the script.
Speed Control
Set the speed parameter between 0.25 and 4.0 to adjust pacing. Use lower values for detailed explanations or higher values for fast-paced ad reads.
Response Formats
Every audio response is a complete audio file that your application can save directly to disk. The API returns the audio file with the correct MIME type, ensuring seamless integration with your podcast hosting pipeline or playback engine.
You choose the format via the response_format parameter. Selecting the right format balances file size, compatibility, and audio fidelity based on whether you are storing assets or playing them to listeners.
MP3 Output
MP3 is the default and most widely supported format for podcast distribution. It offers excellent compression with minimal loss, making it ideal for web delivery and mobile apps where bandwidth matters. Files are typically small enough to cache efficiently on client devices.
Use MP3 when you need broad compatibility across all podcast players and social media platforms. The bitrate is optimized for speech, preserving clarity while keeping file sizes low for faster uploads and downloads.
- Default format for most use cases
- Highly compatible with all podcast apps
- Optimized file size for web delivery
WAV Output
WAV provides uncompressed, lossless audio that preserves every detail of the synthesized voice. This format is ideal if you plan to do further editing, mixing, or mastering in a Digital Audio Workstation (DAW) before publishing.
Choose WAV when audio fidelity is critical for your production quality. The files are larger than MP3, so consider your storage costs and upload bandwidth when generating high-volume content.
- Lossless quality for post-production
- Ideal for editing and mixing
- Larger file sizes than MP3
Other Formats
The API also supports Opus, FLAC, and PCM. Opus offers high-quality compression suitable for modern protocols. FLAC provides lossless compression, reducing file size without sacrificing quality. PCM returns raw audio data, useful for specific low-level processing needs.
Select these formats based on your specific technical requirements. Opus is great for efficient delivery, while FLAC and PCM serve niche workflows where lossless data is mandatory.
- Opus: efficient streaming
- FLAC: lossless compression
- PCM: raw audio data
Code Examples
These examples demonstrate how to integrate our text-to-speech API into your podcast production pipeline. Each snippet handles the standard request structure, ensuring you can generate audio files for intros, narration, or ads with minimal code.
The examples use the OpenAI-compatible SDKs, requiring only a base URL change. This allows you to leverage familiar libraries while accessing our specific voices and pricing structure.
cURL Example
Use this command to generate speech instantly. Replace YOUR_API_KEY with your key from /get-api-key/.
```bash curl https://api.playli789.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Welcome to the show.", "voice": "nova", "response_format": "mp3"}' \ --output intro.mp3 ```
Python SDK
Install openai and configure the base URL to point to our API. This works with the official OpenAI Python package.
```python from openai import OpenAI client = OpenAI(base_url="https://api.playli789.com/v1", api_key="YOUR_API_KEY") with client.audio.speech.create(model="tts-1", voice="aria", input="Hello listeners.", response_format="mp3") as response: response.stream_to_file("episode.mp3") ```
JavaScript SDK
Initialize the client with the correct base URL. The SDK handles the file writing automatically.
```javascript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://api.playli789.com/v1', apiKey: 'YOUR_API_KEY' }); const audio = await client.audio.speech.create({ model: 'tts-1', voice: 'felix', input: 'Ad break starting now.', response_format: 'mp3' }); ```

Error Handling
Handling errors correctly ensures your podcast production pipeline stays smooth without dropping episodes or wasting credits. Our API returns standard HTTP status codes to help you debug issues quickly, whether you are generating intros or full episode narration.
Understanding these responses helps you maintain consistent audio output even during high-volume generation periods or when network conditions fluctuate.
Common Errors
The API returns clear error messages for invalid inputs. If you exceed the 4096 character limit or select an unsupported voice, you will receive a 400 Bad Request. Ensure your JSON body matches the required schema exactly.
- 400 Bad Request: Invalid parameters or format.
- 401 Unauthorized: Missing or invalid API key.
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Temporary service issue.
Rate Limits
You are limited to 60 requests per minute per API key. New accounts without a top-up start with a lower limit of 10 requests per minute. These limits prevent abuse and ensure fair usage for all podcast publishers.
- Standard limit: 60 requests/minute.
- New account limit: 10 requests/minute.
- Limits reset every 60 seconds.
Retry Logic
For transient errors like 500 or 429, implement exponential backoff. Do not retry 400 errors as they will fail again. Always check the error message details to determine if the issue is with your input or our service.
Retrying failed requests is free if the synthesis failed, but successful requests consume your character quota.
Limits and Quotas
Understanding your usage limits helps ensure consistent audio generation for your podcast episodes. Our system balances performance with fairness, so knowing the boundaries prevents unexpected interruptions during high-volume production runs.
Requests Per Minute
Each API key is limited to 60 requests per minute. Before your first top-up, this limit drops to 10 requests per minute.
Character Limits
You can send up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split the text into smaller chunks.
Queue Behavior
Requests are processed sequentially. Under heavy load, your request may wait in a queue before synthesis begins. This ensures stable performance for all users.

Best Practices
Optimizing your podcast production workflow requires managing character limits and language detection carefully. By splitting long scripts and setting explicit language codes, you ensure consistent audio quality and avoid unexpected synthesis failures.
Handling audio files efficiently allows you to assemble seamless episodes without manual editing overhead. This approach keeps your API usage predictable and your final deliverables professional.
Text Splitting
Each API request accepts up to 4,096 characters. For longer monologues or detailed show notes, divide your script into chunks of this size. This prevents truncation and ensures each segment is synthesized cleanly.
Language Codes
While the API guesses language from Latin script (defaulting to English), always set the language parameter for non-English texts. This avoids mispronunciations in languages like Spanish, French, or German, ensuring natural delivery for your audience.
Audio Joining
Since requests are processed sequentially, concatenate the returned audio files to form your final episode. Use standard audio libraries to merge the segments, creating a continuous listening experience that matches your original script structure.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Captivating audio storytelling transforms passive listeners into devoted subscribers, driving sustained growth for forward-thinking publishing houses today.
23 languages
Any voice speaks any of these languages.
