Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playtop99.com/v1. You configure your client to use this endpoint for all requests, including speech synthesis and voice listing. This ensures your application connects directly to the correct infrastructure for text-to-speech processing.
Does it work with the official OpenAI SDK?
Yes, the endpoint shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by changing the base_url to https://api.playtop99.com/v1 and providing your site-specific key. This allows seamless integration without requiring a custom client library.
What is the maximum input length?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, you must split the content into chunks of 4096 characters or less and join the resulting audio files manually.
Can I send audio in WAV format?
Yes, WAV is a supported response format. You specify this by setting the response_format field to 'wav' in your request body. Other supported formats include mp3, opus, flac, and pcm, allowing flexibility based on your application’s audio processing needs.
Is FLAC supported?
Yes, FLAC is supported as a response format. Set the response_format field to 'flac' in your JSON request body. This provides lossless audio quality, suitable for archival or high-fidelity playback scenarios within your SaaS notification or interface systems.
How do I set the speed?
Use the speed parameter in your request body, accepting values between 0.25 and 4.0. Adjusting this value allows you to control the playback rate of the generated synthetic speech to fit your interface context.
What happens if the rate limit is exceeded?
The limit is 60 requests per minute per key (10 before top-up). Exceeding this may cause requests to queue or fail. Failed requests are free, so you are not charged for audio that does not generate successfully due to limits or errors.
Do I need to install a specific SDK?
No, you do not need a specific SDK for this service. You can use the official OpenAI SDK or plain HTTP requests. The API follows standard REST conventions, making it compatible with any HTTP client capable of sending JSON and receiving binary audio.
Is the response JSON or binary?
The response is binary audio data, not JSON. The JSON request body defines parameters like model, voice, and format. The actual output is the audio file itself, streamed directly in the response body according to the specified response_format, such as mp3 or wav.
Can I request multiple voices at once?
No, each request generates audio for a single voice. You specify one voice from the eight available presets in the voice field. To use different voices, you must send separate requests for each voice and join the resulting audio files.
What is the model name?
The model name is either 'tts-1' or 'tts-1-hd'. Both use the same engine and price. You can choose either based on your quality preference, as the underlying synthesis technology remains identical between the two model options for standard and high-definition output.
Are there any required headers?
You must include the Authorization header with your Bearer token: 'Authorization: Bearer tts-...'. This authenticates your request using the key issued to your account.
How do I handle long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Then, join the resulting audio files in your application code. This ensures each chunk is processed within the input limit constraints.
Is streaming supported in the response?
No, streaming is not supported. The API returns the complete audio file after synthesis is finished. There is no WebSocket or real-time partial audio delivery. You receive the full binary response once the request completes, which may take time for long texts.
First request
curl
curl https://api.playtop99.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.playtop99.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.playtop99.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 relies on a single active API key per account, issued via the /get-api-key/ page. Keys follow the format tts-... and must be sent in the Authorization header. This simple scheme avoids complex OAuth flows, allowing immediate integration with existing SaaS notification pipelines.
The key grants access to all endpoints, including speech generation and voice listings. Since only one key is active at a time, rotating credentials is straightforward but requires updating your client configuration promptly to avoid service interruption during the switch.
API Key Format
API keys are issued as strings starting with tts-. They are unique to each account and provide full access to the API. Ensure you copy the key exactly as displayed, as trailing spaces can cause authentication failures.
Keys are generated when you sign up or request a new key. The old key stops working immediately upon issuance of a new one, ensuring no overlap in active credentials.
- Keys start with
tts- - One active key per account
- No scope restrictions
Authorization Header
Include the key in every request using the standard HTTP Authorization header: Authorization: Bearer tts-.... This is compatible with the OpenAI SDK by setting the base URL to https://api.playtop99.com/v1.
Incorrect or missing headers result in a 401 Unauthorized error. Verify that no extra whitespace or line breaks are included in the header value to prevent silent failures.
Key Rotation
You can issue a new key at any time from your dashboard. The previous key becomes invalid immediately, ensuring secure credential management without downtime if updated correctly.
Rotation is ideal for security audits or if a key is suspected to be compromised. No re-authentication flow is needed beyond updating the stored key in your application.
Endpoints
The API exposes three primary endpoints for managing speech synthesis and configuration. Use the speech endpoint to convert text into audio, the voices list to preview available presets, and the models list to verify engine versions.
Speech Generation
Send a POST request to /v1/audio/speech with your JSON payload to receive an audio file. The endpoint accepts up to 4096 characters per request and returns the synthesized audio in the specified format, such as MP3 or WAV.
Voices List
Query GET /v1/voices to retrieve the full list of available voice presets, their associated languages, and supported output formats. This allows you to dynamically match voices to your application’s localization needs.
- Returns 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion
- Includes metadata on supported languages and formats
Models List
Use GET /v1/models to view the available TTS models. Currently, the API offers tts-1 and tts-1-hd, which share the same engine and pricing structure.
Request Parameters
Configuring the speech generation request requires precise handling of three core parameters: model, input text, and voice selection. These fields define the output quality, character limits, and tonal character of the synthesized audio.
Model Selection
Choose between "tts-1" and "tts-1-hd" for standard or high-definition synthesis. Both models use the same engine and pricing tier, so select based on your audio quality requirements without cost implications.
Input Text Length
The API accepts up to 4096 characters per request. For longer content, split the text into chunks, generate audio for each, and join the files. Spaces and punctuation count toward the character limit.
Voice Preset
Select one of eight presets to match your notification style. Female voices include aria, nova, luna, and sage; male options are felix, milo, atlas, and orion. Each voice supports all 23 supported languages.
Response Formats
The API returns audio files in the format specified by your response_format parameter. Supported options include mp3, wav, opus, flac, and pcm, allowing you to choose the best balance between file size and quality for your specific SaaS infrastructure.
MP3 Output
MP3 is a supported format, offering a compact file size suitable for web delivery and mobile notifications. It is ideal for reducing bandwidth costs while maintaining acceptable audio clarity for most user interfaces.
- Default format for most integrations
- Optimized for web and mobile delivery
- Smallest file size for bandwidth efficiency
WAV Output
WAV provides uncompressed, lossless audio data. This format is suitable for applications requiring immediate playback without decoding overhead or where audio integrity is critical for quality assurance.
- Uncompressed audio data
- No decoding overhead for playback
- Ideal for quality assurance workflows
Lossless Formats
FLAC and PCM offer lossless alternatives. FLAC provides compression without data loss, while PCM delivers raw audio streams. These formats are useful for archival purposes or high-fidelity audio processing pipelines.
- FLAC: Compressed lossless audio
- PCM: Raw uncompressed audio stream
- Suitable for archival or processing pipelines
Speed Control
Adjust speech playback speed between 0.25x and 4.0x to fit interface constraints or user preferences. This parameter modifies the audio output in real-time without requiring separate voice models, allowing SaaS teams to optimize character consumption for long notifications.
Speed Range 0.25–4.0
Set the speed field in your request body to control voice pacing. Values below 1.0 slow the narration, while values above 1.0 accelerate it.
Real-Time Generation
Long texts generate at roughly real-time speed, processing approximately 25 characters of text per second of audio. Short phrases may take a few seconds to synthesize due to initialization overhead, but complex processing remains minimal.
Queue Impact
Requests are processed sequentially. Under heavy load, your synthesis job may wait in a queue before beginning. This linear processing ensures consistent quality but means concurrent requests from different keys will not accelerate individual generation times.

Error Handling
Handling errors correctly ensures your application remains resilient during high-volume TTS generation. Understanding HTTP status codes and rate limits allows you to implement robust retry logic without wasting credits on failed requests.
Common HTTP Errors
Returns standard HTTP codes like 400 for bad requests, 401 for invalid keys, and 500 for internal server issues. Failed synthesis requests are free, ensuring you are not charged for errors.
Rate Limit Exceeded
Exceeds the 60 requests per minute limit per key. New accounts start with a 10 requests per minute limit until the first top-up. Implement exponential backoff to handle 429 responses gracefully.
Invalid Input
Returns 400 if input text exceeds 4096 characters or if the voice ID is invalid. Ensure your client splits long texts into chunks before sending requests to avoid input errors.
OpenAI SDK Setup
The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDKs with minimal configuration. By simply updating the base_url to https://api.playtop99.com/v1, your application can authenticate and send requests using standard libraries.
This compatibility ensures that teams already familiar with OpenAI’s integration pattern can adopt our service without learning a new SDK or rewriting core logic. The request shape remains identical, supporting the same JSON body structure for model, input, voice, and format parameters.
Base URL Change
Update your SDK client configuration to point base_url at https://api.playtop99.com/v1. This single change redirects all subsequent API calls to our infrastructure while maintaining the familiar endpoint paths.
SDK Compatibility
The official OpenAI SDKs work out-of-the-box. No custom wrapper is required, as the JSON body structure matches the OpenAI speech endpoint exactly. You can use the same base_url and authentication headers you would use for OpenAI, replacing only the domain.
- Supports standard OpenAI Python and Node.js SDKs
- Identical JSON request body structure
- No additional libraries or dependencies required
Code Example
Here is a minimal Python example using the OpenAI SDK to generate speech. Replace YOUR_API_KEY with your key from /get-api-key/ and set the base_url correctly.
- ```python
- import openai
- client = openai.OpenAI(api_key='tts-...', base_url='https://api.playtop99.com/v1')
- response = client.audio.speech.create(
- model='tts-1',
- voice='nova',
- input='Hello from Playtop99',
- response_format='mp3'
- )
- response.write_to_file('output.mp3')
- ```
Rate Limits
Rate limits are enforced per API key to ensure fair usage across the network. Understanding these constraints helps SaaS teams design robust retry logic and manage background notification queues effectively.
60 RPM Limit
After your initial top-up, you may send up to 60 requests per minute. This limit applies to the tts-1 and tts-1-hd models collectively. If you exceed this threshold, the API returns a 429 Too Many Requests error. Implement exponential backoff in your integration to handle temporary spikes without dropping notifications.
Pre-Topup Limit
Before your first top-up, the limit is stricter at 10 requests per minute. This allows new accounts to test the service without overwhelming the infrastructure. Once you add USDT (TRC-20), the higher 60 RPM limit activates automatically.
Concurrency
Requests are processed sequentially within the rate limit window. Under heavy load, your request may wait in a queue before synthesis begins. This ensures consistent audio quality but means that bursty traffic patterns might experience slight delays compared to steady-state usage.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your team receives seamless alerts directly within the unified interface for instant awareness and streamlined collaboration.
23 languages
Any voice speaks any of these languages.
