Frequently asked questions
How do I generate an API key?
Navigate to /get-api-key/ and sign up using Google or an email and password. Your unique API key appears on the dashboard immediately. You can issue a new key at any time, which instantly invalidates the previous one, ensuring secure access for your localization projects.
Can I use the OpenAI Python SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. Simply update the base_url to https://api.playyy9.com/v1 in your OpenAI SDK configuration. This allows you to use standard OpenAI client libraries without writing custom HTTP logic for your dubbing pipeline.
What is the maximum text length?
Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer scripts, split your text into chunks of 4096 characters or less, generate each segment, and join the resulting audio files to create your final voice-over.
How do I set the voice parameter?
Include one of the eight preset voice names in the voice field of your JSON request body. Available options include aria, nova, luna, sage, felix, milo, atlas, and orion. You can view the full list and details by sending a GET request to /v1/voices.
Can I adjust the speed of the audio?
Yes, use the speed parameter to control playback rate. Acceptable values range from 0.25 to 4.0. This allows you to fine-tune the pacing of your localized content to match the original video’s timing or to fit specific character limits within your dubbing workflow.
Do I need to specify the language?
It is recommended to set the language field using an ISO code. If omitted, the system guesses the language, defaulting to English for Latin script. For non-English Latin text, explicitly setting the language ensures accurate pronunciation and prevents misidentification in your localization projects.
What happens if I exceed the rate limit?
The API allows 60 requests per minute per key (10 per minute before your first top-up). If you exceed this limit, your requests will be queued and processed sequentially. Under heavy load, generation may take longer than usual as requests wait in line.
Is the API synchronous or asynchronous?
The API is synchronous. You send a POST request to /v1/audio/speech and receive the audio file directly in the response. There is no WebSocket or streaming support for partial audio, so you must wait for the full synthesis to complete before receiving the file.
How do I handle large files?
Split your input text into segments of up to 4096 characters. Send each segment as a separate request to the speech endpoint. Once you receive all the individual audio files, concatenate them in order to create the final continuous audio file for your dubbing project.
Can I use the same key on multiple projects?
Yes, you can use your single active API key across multiple projects or services. Each account has one active key, but you can issue a new key at any time if needed. The new key becomes active immediately, and the old one stops working at once.
What is the response format?
You can specify the response_format as mp3, wav, opus, flac, or pcm. The API returns the generated audio file directly in the HTTP response body. This allows you to integrate the audio directly into your video editing or localization pipeline without additional conversion steps.
Do I need to install extra libraries?
No extra libraries are required beyond standard HTTP clients. You can use plain HTTP requests or the official OpenAI SDKs by adjusting the base URL. No custom SDK or mobile library is needed, making integration straightforward for your existing development workflows and automation scripts.
How do I authenticate my requests?
Include your API key in the Authorization header as a Bearer token. The format is Authorization: Bearer tts-.... Ensure you use the key generated from your account dashboard. Failed requests are free, so authentication errors will not incur charges against your balance.
What are the common error codes?
The API uses standard HTTP status codes. Common errors include 401 for invalid authentication, 429 for rate limit exceeded, and 400 for invalid parameters like unsupported voices or format. Failed synthesis requests are free, so you can retry without worrying about character consumption on errors.
First request
curl
curl https://api.playyy9.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.playyy9.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.playyy9.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 |
Get Your API Key
Access the /get-api-key/ page to create your VoxLocale account. This is the entry point for obtaining the credentials needed to call our TTS API. You will need an active account to generate the bearer token required for authentication.
Sign Up on /get-api-key/
Navigate to the sign-up page to register. You can create an account using your Google account or by providing an email address and password. Each site in our network maintains independent accounts, so ensure you are signing up on the correct domain.
- Independent account per site
- No minimum spend required
Google or Email Authentication
You may authenticate via Google SSO or traditional email/password login. Google sign-ups receive a $0.50 free trial credit valid for 7 days. Email-based accounts start with zero balance and require a top-up before use.
Copy Your Bearer Token
After logging in, locate your API key on the dashboard. This key starts with 'tts-' and serves as your Bearer token. Copy it securely; you will include it in the Authorization header of every API request.
- Format: Bearer tts-...
- One active key per account
Make Your First Request
Send a POST request to https://api.playyy9.com/v1/audio/speech with your text payload. The API returns the generated audio file directly in the response body, allowing you to save it or pass it to your dubbing pipeline.
cURL Example
Use this command to generate speech with the nova voice in English. Replace YOUR_API_KEY with your token from /get-api-key/.
- curl -X POST "https://api.playyy9.com/v1/audio/speech" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'
JSON Body Structure
The request body is standard JSON. You can include optional fields like speed (0.25–4.0) or language to override auto-detection.
Required Fields
Three fields are mandatory for every synthesis job.
- model: "tts-1" or "tts-1-hd"
- input: Text string (max 4096 characters)
- voice: One of the 8 available presets
OpenAI SDK Integration
Leverage existing OpenAI client libraries to integrate VoxLocale’s TTS API with minimal code changes. By simply adjusting the base URL configuration, you can utilize the official SDKs without rewriting request logic or handling authentication headers manually.
Set base_url
Configure your OpenAI SDK client to point to the VoxLocale API endpoint. This ensures all standard speech generation methods route through our infrastructure while maintaining the familiar request structure.
Use Official SDK
The official OpenAI SDKs work seamlessly because our endpoint shape matches theirs. You can continue using your preferred language client (Python, Node.js, etc.) without learning a new API syntax.
Change Endpoint URL
Update the base URL to https://api.playyy9.com/v1. This directs requests to our processing servers, allowing you to use standard voice and model parameters immediately.
Available Voices
VoxLocale provides eight distinct voice presets designed to cover the full spectrum of localization needs. Each voice is derived from licensed LibriTTS-R and public-domain LibriVox readings, ensuring clear, high-quality audio for dubbing pipelines without the need for hiring additional talent.
Aria and Nova (Female)
Aria offers a warm, clear narration style. Nova delivers a bright, upbeat tone. Both voices support all 23 languages, allowing consistent character branding across global releases.
Felix and Milo (Male)
Felix brings an energetic, promo-ready energy. Milo provides a friendly, conversational tone. Like all voices, they handle multi-language scripts seamlessly without accent drift.
Atlas and Orion (Neutral/Deep)
Atlas serves as a neutral, news-style voice. Orion offers a deep, documentary-grade tone. Both are optimized for clarity and can be adjusted via the speed parameter (0.25–4.0) to fit exact timing requirements.
Supported Formats
VoxLocale supports MP3, WAV, OPUS, and FLAC output formats, letting you choose the right balance of quality and file size for your dubbing pipeline. Selecting the appropriate format ensures seamless integration with your existing audio editing and localization workflows.
MP3 for Web
MP3 is a standard choice for web playback. It offers a compact file size while maintaining clear audio quality, making it ideal for quick delivery to final clients or embedding in video players.
- Ideal for web playback and streaming
- Compact file size for faster delivery
- Broad compatibility with media players
WAV for Editing
Choose WAV when you need uncompressed audio for professional editing. This format preserves the full fidelity of the generated speech.
- Uncompressed, high-fidelity audio
- Perfect for professional post-production
- No quality loss during editing
FLAC and OPUS Options
FLAC provides lossless compression, while OPUS offers efficient quality at low bitrates. Both formats provide efficient storage without sacrificing the clarity needed for voice-over work.
- FLAC: Lossless compression for masters
- OPUS: Efficient bandwidth usage
- High quality at low bitrates

Rate Limits and Quotas
VoxLocale provides a reliable TTS API designed for automation pipelines. Understanding rate limits ensures your dubbing jobs process smoothly.
60 Requests Per Minute
Each API key supports up to 60 requests per minute once fully active. This limit applies to all synthesis endpoints and ensures stable performance for your automated workflows.
10 Requests Before Top-Up
New accounts start with a lower quota of 10 requests per minute. This applies until you complete your first top-up via USDT (TRC-20). Once credited, your limit increases to the full 60 requests per minute.
Queue Processing
Requests are processed sequentially. If you exceed the rate limit or hit peak load, new requests may wait in a queue. Longer texts generate in roughly real-time, so plan your batching strategy to avoid bottlenecks during large-scale dubbing projects.
Error Handling
When integrating the TTS API, understanding error responses ensures your dubbing pipeline remains robust. Client errors typically indicate issues with your request payload, authentication, or rate limits, while server errors suggest temporary infrastructure hiccups that you can safely retry.
4xx Client Errors
A 4xx response (e.g., 400 Bad Request, 401 Unauthorized, or 429 Too Many Requests) indicates an issue with your specific request. Common causes include invalid JSON syntax, an expired or incorrect Bearer token, or exceeding the 60 requests per minute limit. Ensure your model, voice, and input fields are correctly formatted before retrying.
- 401: Check your Bearer token validity.
- 429: Wait before retrying to respect rate limits.
5xx Server Errors
Server errors (500–503) are rare but may occur during peak load or brief maintenance. These indicate the API service itself encountered an issue. Since failed synthesis requests are free, you are not charged for retries triggered by 5xx errors, making it safe to implement exponential backoff without financial risk.
Retry Logic
Implement exponential backoff for both 429 and 5xx errors. Start with a short delay (e.g., 1 second) and double it with each attempt. For 429 errors, always respect the Retry-After header if provided. This strategy prevents overwhelming the queue during high-demand periods, ensuring your audio files are delivered smoothly.
- Use exponential backoff for transient errors.
- Respect
Retry-Afterheaders for rate limits.
Text Processing Rules
The API enforces a strict 4096-character limit per request, counting all spaces and punctuation. This constraint limits the size of each request.
4096 Character Limit
Each API call accepts input text up to 4096 characters. Exceeding this limit results in a 400 Bad Request error. The character count includes every space, comma, and special character in your payload.
Manual Splitting for Long Text
For longer scripts, split your text into chunks of 4096 characters or fewer. Submit each chunk as a separate POST request. This approach maintains audio quality and ensures reliable delivery for dubbing pipelines.
Audio Joining Strategy
Receive individual audio files for each chunk. Concatenate these files sequentially to reconstruct the full narration. Since requests are processed sequentially, ensure your client handles the output files in the correct order to avoid audio gaps.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Unlike many consumer-grade platforms, we do not use your input text to train our models.
23 languages
Any voice speaks any of these languages.
