Frequently asked questions
How do I get my API key?
Sign up on the /get-api-key/ page using Google or an email and password. The dashboard displays your unique API key, current balance, and usage statistics. You can also generate a new key at any time, which immediately invalidates the previous one.
Can I use the OpenAI Python SDK with this API?
Yes. The endpoint shape matches the OpenAI speech endpoint. Update your SDK’s base_url to https://api.playa02.com/v1 and provide your Playa Voice API key. The official OpenAI SDKs work seamlessly without requiring any custom client libraries or additional configuration.
What is the maximum length of the input text?
Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4096 characters or less, generate audio for each part, and join the resulting audio files.
Which models are available for synthesis?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure. You can select either model in your request body without any difference in voice quality or generation speed, only the model identifier changes.
How do I specify the output format?
Include the response_format field in your JSON body. Supported formats are mp3, wav, opus, flac, and pcm.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key (10 per minute before the first top-up). Exceeding this limit may result in delayed processing or rejected requests. Requests are processed sequentially, so high volume can cause queuing delays.
Is the API key the same for all endpoints?
Yes, use a single Bearer token for all endpoints. Pass it via the Authorization header as Bearer tts-... . This key authenticates requests to /v1/audio/speech, /v1/voices, and /v1/models uniformly across your account.
Can I change my voice after generating audio?
No. Once audio is generated, it is returned in the response and not stored. To change the voice, you must send a new request with the desired voice preset. The generated file carries a synthetic watermark and cannot be modified.
How do I handle long texts exceeding 4096 characters?
Split the text into parts of up to 4096 characters. Send each part as a separate POST request to the speech endpoint. Then, join the resulting audio files from each response to create the final continuous audio output.
Does the API support SSML tags?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. Input is plain text only. For precise control, you must adjust the text content or use the speed parameter to modify playback rate.
What is the default language if none is specified?
If the language field is omitted, the system guesses the language from the script. Latin script text defaults to English. For non-English Latin text, explicitly set the language parameter to ensure accurate synthesis.
How do I rotate my API key?
Issue a new key from your dashboard at any time. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime for your integrated applications.
Are there webhooks for status updates?
No. The API does not provide webhooks for status updates or delivery notifications. Request metadata is kept for billing purposes. You must poll or handle responses synchronously to track synthesis status and retrieve audio files.
Can I use this API in a serverless environment?
Yes. The API is stateless and accessible via standard HTTP requests. It works well in serverless environments. Ensure your environment handles the 4096-character limit and rate limits appropriately for concurrent invocations.
First request
curl
curl https://api.playa02.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.playa02.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.playa02.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 and Keys
Access to the Playa Voice API requires a valid API key issued to your account. You can generate or retrieve your key on the /get-api-key/ dashboard page, where it is displayed alongside your current balance and usage metrics.
Each account is limited to one active key at a time. This design simplifies integration while ensuring clear attribution for billing and rate-limiting purposes.
Generating Your API Key
Sign up via the /get-api-key/ page using Google or an email/password combination. Once authenticated, the dashboard displays your unique key, which begins with "tts-". This key is the sole credential for all API requests.
Bearer Token Usage
Include your key in the HTTP Authorization header of every request using the format: Authorization: Bearer tts-your-key-here. Omitting this header or using an invalid key will result in a 401 Unauthorized response.
Key Rotation and Invalidation
You can issue a new key at any time from the dashboard. When a new key is generated, the previous key becomes invalid immediately. This allows for instant revocation without waiting for expiration.
- One active key per account
- Old key stops immediately upon new generation
- No downtime during rotation if updated in code
Endpoint Overview
The API exposes three primary endpoints for integration. The core synthesis endpoint accepts text and configuration parameters to return audio files. Metadata endpoints provide information on available voices and model configurations.
These endpoints follow standard REST conventions, making them compatible with existing HTTP clients and the official OpenAI SDKs. Developers can retrieve voice lists and model details to configure their requests accurately.
POST /v1/audio/speech
This endpoint accepts a JSON body containing the text to convert, the selected voice, and optional parameters like speed or format. It returns the synthesized audio file directly in the response body, allowing immediate playback or storage.
Each request is limited to 4096 characters. For longer texts, split the input into multiple requests and concatenate the resulting audio files.
- Accepts JSON input with
input,voice, andmodelfields - Returns audio data in the requested format (mp3, wav, opus, flac, or pcm)
- Processes requests sequentially; queueing may occur under high load
GET /v1/voices
Returns a list of all available voice presets, their associated languages, and supported output formats. This endpoint helps developers select the appropriate voice for their specific use case.
Each voice preset is designed for specific tones, from warm narration to energetic promo styles, and supports all 23 supported languages.
- Lists all 8 voice presets with metadata
- Shows supported languages and formats for each voice
- Provides voice metadata and supported formats
GET /v1/models
Returns information about the available TTS models, including tts-1 and tts-1-hd. Both models use the same engine and pricing structure.
Use this endpoint to verify model availability and ensure compatibility with your integration setup before sending synthesis requests.
- Lists
tts-1andtts-1-hdmodels - Shows model capabilities and pricing details
- Confirms compatibility with OpenAI SDK request shapes
Request Parameters
Configure the synthesis engine and payload constraints to ensure reliable audio generation. Select the appropriate model and input parameters to match your latency and quality requirements.
Model Selection: tts-1 vs tts-1-hd
Both "tts-1" and "tts-1-hd" utilize the same underlying engine and incur identical pricing. Choose based on your quality preference, as the engine behavior remains consistent across both options.
Input Text and Character Limit
Provide your script in the input field, with a strict maximum of 4096 characters per request. Spaces and punctuation are counted toward this limit. For longer texts, split the input into chunks and join the resulting audio files.
Voice Selection and Speed
Select one of eight presets from the voice parameter, such as aria or atlas. Adjust the speed between 0.25 and 4.0 to control playback tempo without altering the voice identity.
Response Formats
The API returns synthesized audio directly in the response body, allowing seamless integration into your notification systems without intermediate storage steps. You specify the desired output format via the response_format parameter, choosing from MP3, WAV, Opus, FLAC, or PCM to match your infrastructure’s requirements.
Supported Output Formats: MP3, WAV, Opus, FLAC, PCM
Each format offers different trade-offs between file size and compatibility. MP3 and Opus provide efficient compression for web delivery, while WAV and FLAC offer lossless quality for archival or high-fidelity playback systems. PCM is available for raw, uncompressed audio data.
Audio Data in Response Body
Successful synthesis responses contain the binary audio data directly in the body. The Content-Type header matches the requested format, ensuring your application can process the data immediately without parsing complex JSON structures for large files.
Error Response Structure
Errors return standard HTTP status codes with a JSON body detailing the issue. Failed requests are free, so you are not charged for audio that was not generated. Common errors include invalid parameters or rate limit exceedances, clearly described in the response payload.
Rate Limits and Quotas
The API enforces a standard rate limit of 60 requests per minute for each active key. This ceiling ensures stable performance for SaaS notification systems processing bulk audio generation without overwhelming the underlying synthesis engine.
Standard Limit: 60 Requests Per Minute
After initial top-ups, accounts operate at the standard limit of 60 requests per minute. This throughput supports consistent delivery of synthetic audio for user notifications and in-app interfaces, provided requests are not excessively bursty.
Initial Limit: 10 Requests Per Minute
New accounts without a top-up history begin with a conservative limit of 10 requests per minute. This constraint applies until the first top-up is completed, after which the standard 60 requests per minute limit activates.
Handling 429 Too Many Requests
When the limit is exceeded, the API returns a 429 status code. Implement exponential backoff in your integration logic to queue requests gracefully. Since requests are processed sequentially, queuing prevents wasted characters on failed submissions during peak load.
- Implement client-side queuing for bulk text processing.
- Retry with increasing delays upon receiving a 429 status.

OpenAI SDK Compatibility
Playa Voice is engineered for seamless interoperability with existing TTS workflows. By adjusting the API base URL, development teams can leverage the official OpenAI SDKs without rewriting core logic or dependency trees. This compatibility ensures that standard integration patterns remain intact while accessing our specific voice models and pricing structure.
Changing Base URL
Point your SDK client to https://api.playa02.com/v1 instead of the default OpenAI endpoint. This single configuration change routes all requests to our infrastructure while maintaining the same JSON request shape and authentication headers.
Using Official SDKs
The official OpenAI Python and Node.js libraries work directly with our endpoint. You only need to provide your Bearer token and update the base URL. No custom client wrappers or middleware are required to handle our response formats.
Example Code Snippet
import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env.PLAYA_API_KEY, baseURL: 'https://api.playa02.com/v1' }); const audio = await client.audio.speech.create({ model: 'tts-1', voice: 'nova', input: 'Hello from Playa Voice' });
Language and Voice Handling
Playa Voice supports 23 languages, allowing any voice preset to speak any supported language. The API attempts to detect the language automatically from the script, defaulting to English for Latin text. However, for non-English Latin-script content, you should explicitly set the language parameter to ensure accurate synthesis.
Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish. Languages such as Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, and Bengali are not supported.
Auto-Detection vs Explicit Language
Language detection relies on the input script. If the language field is omitted, the API guesses the language based on the characters provided. For Latin-script text that is not English, always specify the language code to avoid incorrect defaults.
Voice Presets List
Our eight voice presets are derived from licensed recordings of LibriTTS-R and LibriVox. Each voice offers a distinct tone suitable for different notification or interface contexts.
Female voices: Aria (warm, clear narrator), Nova (bright, upbeat), Luna (soft, storytelling), and Sage (calm, instructional). Male voices: Felix (energetic, promo), Milo (friendly, conversational), Atlas (neutral, news), and Orion (deep, documentary).
- 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
Speed Range: 0.25 to 4.0
You can adjust the playback speed between 0.25x and 4.0x to fit your interface’s pacing. This allows for faster notifications or slower, clearer instructional audio.
Note that generation speed is roughly real-time, averaging about 25 characters of text per second of audio. Requests are processed sequentially, so high-volume loads may introduce queue delays.
Error Codes and Troubleshooting
API responses follow standard HTTP conventions. A 200 OK status indicates successful synthesis, while 400 errors signal input issues. Authentication failures return 401, and server-side processing errors return 500.
Failed synthesis requests are free, with the charge returned in full. Always check the response body for specific error messages to debug integration issues quickly.
Common HTTP Error Codes
Use standard HTTP status codes to determine the request state. 200 means success, 401 indicates an invalid or expired API key, and 400/422 signals malformed input data.
Server errors (5xx) are rare but indicate temporary processing issues. Retrying with exponential backoff is recommended for server errors.
Input Validation Errors
Errors occur if the input text exceeds 4096 characters or if the voice ID is invalid. Ensure the model is either tts-1 or tts-1-hd.
Missing required fields like input or voice will return a 400 error. Verify your JSON structure matches the expected schema before sending.
- Text must be under 4096 characters per request.
- Supported models: tts-1, tts-1-hd.
- Valid voices are listed in GET /v1/voices.
Rate Limit Exceeded Errors
If you exceed 60 requests per minute, the API returns a 429 Too Many Requests error. New accounts start with a limit of 10 requests per minute.
Handle 429 errors by implementing a retry loop with backoff. Monitor your usage dashboard to stay within limits and avoid interruptions during high-volume synthesis.
- Standard limit: 60 requests/minute.
- Initial limit: 10 requests/minute.
- Retries should use exponential backoff.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. This simplicity allows engineering teams to forecast costs accurately as user bases grow, without renegotiating contracts or managing seat counts.
23 languages
Any voice speaks any of these languages.
