Frequently asked questions
How do I authenticate my API requests?
Include your unique API key in the request header as Authorization: Bearer tts-.... Each account holds one active key at a time. If you issue a new key, the previous one stops immediately. This ensures secure access to the speech synthesis endpoint.
What is the maximum text length per request?
Each request supports up to 4096 characters of input text. For longer content, split your text into chunks of this size and join the resulting audio files. This limit applies to the input field in the JSON body, ensuring consistent processing times and predictable billing calculations for your application.
Can I change the speed of the speech?
Yes, you can adjust the playback speed between 0.25 and 4.0 using the speed parameter. This allows you to slow down narration for clarity or speed up content for brevity. The default speed is 1.0.
Which audio formats are supported?
You can choose from mp3, wav, opus, flac, or pcm via the response_format field. MP3 offers efficient compression, while WAV and FLAC provide lossless quality. PCM is raw audio data. Select the format that best fits your storage constraints and playback requirements for the generated speech files.
How do I list available voices?
Send a GET request to /v1/voices to retrieve all available voice presets, languages, and formats. This endpoint provides the necessary metadata to configure your application correctly. You can then select from eight distinct voices, including female and male options.
What happens if I exceed the rate limit?
The standard limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a lower limit of 10 requests per minute until the first top-up. Exceeding limits does not incur extra charges but may delay audio generation.
Do I need to install a specific SDK?
No specific SDK is required. You can use the official OpenAI SDKs by changing the base_url to https://api.playv57.com/v1. Alternatively, use any standard HTTP client to send JSON requests. This flexibility allows integration with existing infrastructure without needing to install proprietary libraries or manage complex dependencies.
Is the API endpoint stable?
The endpoint https://api.playv57.com/v1/audio/speech uses a standard versioned path. Requests follow a consistent JSON shape similar to OpenAI’s speech endpoint. No SLA is guaranteed. Use the documented fields to ensure compatibility across updates without breaking changes.
Can I send multiple texts in one request?
No, each request processes a single input string up to 4096 characters. To generate audio for multiple texts, send separate requests. You can parallelize these requests if your rate limit allows, or process them sequentially. This design ensures precise control over each audio segment’s parameters and formatting.
How do I handle audio file responses?
The API returns the audio file directly in the response body. Save this binary data to your desired storage or stream it to the user. The file includes an inaudible watermark marking it as synthetic. Ensure your client handles the specific response_format you requested, such as MP3 or WAV.
What is the default voice if none is specified?
If you do not specify a voice, the system uses a default voice. The available voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion. Explicitly setting the voice ensures consistent output. Defining the voice parameter is recommended for predictable results.
Can I specify a language explicitly?
Yes, use the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation for non-English texts.
Are there any version constraints?
The API uses version v1 in the endpoint path. Models tts-1 and tts-1-hd are supported. There are no complex version constraints beyond the standard API structure. Ensure your client sends requests to the correct base URL. The endpoint format remains consistent, allowing straightforward integration without frequent updates.
How do I test the API before buying?
Sign up with Google to receive a $0.50 free trial credit, valid for 7 days. This allows approximately 50,000 characters of generation. You can test voices, formats, and speed settings without immediate payment. Email-based accounts start without this trial credit, so consider using Google sign-in for initial testing.
First request
curl
curl https://api.playv57.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.playv57.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.playv57.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
Authentication is handled via a Bearer token passed in the Authorization header. This single key grants access to all endpoints and is tied to your account balance.
Bearer token in header
Include Authorization: Bearer tts-... in every request. The token authenticates your identity and deducts usage from your available credit.
One active key per account
Each account maintains only one active API key at a time. This simplifies credential management for indie developers and small teams.
Revoke and issue new keys
You can issue a new key at any time from the dashboard. The previous key stops working immediately, ensuring no overlap or security gaps.
- No downtime during rotation
- Immediate invalidation of old key
- Manage keys via /get-api-key/
Speech Endpoint
The core of the API is the speech generation endpoint. You send text data to this specific route to receive synthesized audio files. It follows the same request shape as the OpenAI speech endpoint, allowing you to use standard HTTP clients or the official OpenAI SDK by simply adjusting the base URL.
This endpoint handles the conversion of your input text into audio. It is designed for reliability and straightforward integration into web applications and scripts.
POST /v1/audio/speech
Send a POST request to https://api.playv57.com/v1/audio/speech. This is the only endpoint required for generating audio files from text inputs.
The endpoint accepts standard JSON payloads and returns binary audio data directly in the response body.
JSON request body
The request body must include the input text (up to 4096 characters), a model (tts-1 or tts-1-hd), and a voice preset. Optional fields include response_format, speed, and language.
Ensure you provide a valid API key in the Authorization header. The system processes requests sequentially, so longer texts may queue under load.
model: "tts-1" or "tts-1-hd"input: string, max 4096 charsvoice: one of 8 presetsresponse_format: mp3, wav, opus, flac, pcmspeed: 0.25–4.0language: optional ISO code
Returns audio file
On success, the API returns the audio file in the requested format. Failed requests are free, meaning no charge is applied if synthesis fails.
You can save the response directly to a file or pass it to your application's audio player.
Request Parameters
The API accepts text up to 4,096 characters per request. For longer content, split the text into chunks and join the resulting audio files. This limit applies to every call, regardless of the model chosen.
Model selection (tts-1, tts-1-hd)
Choose between "tts-1" and "tts-1-hd". Both use the same engine and pricing, so the decision depends on your audio quality preference rather than cost differences.
Input text limit
Send up to 4,096 characters in the input field. Spaces and punctuation count toward this limit. If your content exceeds this, process multiple requests and concatenate the output files.
Voice and language settings
Select one of eight preset voices, such as aria or atlas. You can optionally specify a language ISO code. If omitted, the system guesses the language, defaulting to English for Latin script text.
Setting the language explicitly is recommended for non-English Latin-script inputs to ensure accurate pronunciation.
Response Formats
The API returns synthesized audio in the requested format, allowing you to choose the optimal balance between file size and quality for your web app. All formats are delivered as binary data in the response body, ready to be saved or passed to the user’s player.
Choosing the right format ensures efficient bandwidth usage and broad compatibility across different devices and browsers without requiring additional conversion steps on your server.
MP3 support
MP3 is the default and most widely supported format for web playback. It offers a good balance between audio quality and file size, making it ideal for general use cases where storage efficiency matters.
- Compatible with all major browsers
WAV support
WAV provides uncompressed, high-fidelity audio. Use this format when you need maximum quality for professional applications or when further processing of the audio file is required without compression artifacts.
- Uncompressed audio quality
OPUS and FLAC options
OPUS offers superior compression efficiency, ideal for mobile data conservation. FLAC provides lossless compression, preserving exact audio quality while reducing file size compared to WAV, suitable for archival purposes.
- Optimized for mobile data
- Lossless audio preservation
Rate Limits
Rate limits protect service stability during peak usage. Each API key allows up to 60 requests per minute once your account is funded. This limit applies per key, so you can manage throughput by distributing requests across multiple keys if needed.
60 requests per minute
Once your balance is active, you can send 60 synthesis requests per minute. This throughput is sufficient for most batch processing or moderate real-time applications. Requests are processed sequentially, so high concurrency may introduce slight delays.
10 requests before top-up
New accounts start with a restricted limit of 10 requests per minute. This allows you to verify the service quality before committing funds. You can top up via USTRC20 at any time to unlock the full 60 requests/minute capacity.
Queued processing
Under heavy load, requests may wait in a queue before synthesis begins. This ensures fair resource distribution among all users. You should implement retry logic with exponential backoff in your client code to handle transient delays gracefully.

Voices List
Retrieve available voices, supported languages, and pricing tiers with a simple GET request. The /v1/voices endpoint provides a static list of all 8 presets, allowing you to verify availability before generating audio. This metadata includes the voice ID, gender, and style description, ensuring you select the right tone for your application.
GET /v1/voices endpoint
Send a GET request to https://api.playv57.com/v1/voices with your Bearer token. The response returns a JSON array of voice objects, detailing their capabilities and supported languages. This endpoint is ideal for populating dropdown menus in your UI dynamically.
8 preset voices
Choose from four female and four male voices, each designed for specific use cases. Options range from the warm narration of aria to the energetic promo style of felix. All voices can speak any of the 23 supported languages, allowing for flexible multilingual content.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
Voice metadata details
Each voice object includes the ID required for the voice parameter, along with gender and style tags. The response also confirms supported response formats and language capabilities. Use this data to map UI labels to the correct API IDs, ensuring seamless integration without manual lookup tables.
Error Handling
The API returns standard HTTP status codes to indicate request success or failure. Understanding these codes helps you implement robust retry logic in your web applications without unnecessary delays or repeated failures.
Standard HTTP errors
Use 4xx codes for client-side issues like authentication failures or malformed JSON. Use 5xx codes for internal server errors that you can safely retry after a short delay.
Invalid input responses
If your text exceeds 4096 characters or specifies an unsupported voice, the API returns a clear error message. Ensure you validate input length and voice IDs before sending requests to avoid wasted API calls.
- Check character count against the 4096 limit
- Verify voice names against the /v1/voices endpoint
Rate limit exceeded messages
Exceeding 60 requests per minute returns a 429 status code. New accounts start with a 10 requests per minute limit until the first top-up is processed. Implement exponential backoff to handle these throttles gracefully.
SDK Integration
We use the official OpenAI SDKs by simply redirecting the base URL. This allows you to leverage familiar client libraries without learning a new interface, ensuring smooth integration for indie developers already using standard TTS patterns.
OpenAI SDK compatibility
Our API mirrors the request shape of the OpenAI speech endpoint. You can use the same SDKs, sending JSON bodies with model, input, voice, and format fields. This compatibility reduces boilerplate code and testing time for your web apps.
Base URL configuration
Point your SDK client to https://api.playv57.com/v1. Replace the default OpenAI base URL with this domain. Ensure your Authorization header includes your tts-... bearer token for authentication.
Example code snippet
Here is a minimal Python example using the OpenAI SDK. It sends a short text and receives the audio bytes directly, ready for playback or storage in your application.
- import openai
- client = openai.OpenAI(base_url="https://api.playv57.com/v1", api_key="tts-...")
- response = client.audio.speech.create(model="tts-1", voice="nova", input="Hello world")
- response.stream_to_file("output.mp3")
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Creating games alone is hard work but the freedom to follow your creative vision makes every late night worth it.
23 languages
Any voice speaks any of these languages.
