Frequently asked questions
How do I get an API key?
Sign up at /get-api-key/ using Google or email. Accounts are per site. You receive one active key per account, visible on the dashboard. You can issue a new key anytime; the old one stops immediately. Failed requests are free, and a $0.50 trial credit is available for Google sign-ups.
What is the base URL?
The API base URL is https://api.playz555.com/v1. Use this endpoint for all requests. The standard OpenAI SDKs work by setting this base_url. Send POST requests to /v1/audio/speech with your JSON body and Bearer token authentication header containing your API key.
Which models are available?
Two models are available: tts-1 and tts-1-hd. They use the same engine and price. Select the model in your request body. Both support the same voices and formats. The choice does not affect pricing, which is $10 per million characters.
What is the character limit?
Each request supports up to 4096 characters. Spaces and punctuation count toward this limit. For longer texts, split the input into parts of 4096 characters. Generate audio for each part and join the resulting files to create the final audio.
Can I change the voice after request?
No, you cannot change the voice after the request is sent. The voice is determined by the voice parameter in the request body. You must specify the desired voice, such as aria or nova, before generating the audio file.
How do I set the language?
Set the language using the optional ISO code in the request body. If omitted, the system guesses the language from the script. Latin text defaults to English. For non-English Latin-script text, explicitly set the language to ensure correct pronunciation.
What formats are supported?
Supported formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the response_format field of your request. The audio file is returned directly in the response. All voices support all these formats equally.
Does the API support streaming?
No, the API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. Requests are processed sequentially, so under load, a request may wait in a queue before generation begins.
How do I handle errors?
If synthesis fails, the charge is returned in full. Check the response status code for error details. Ensure your text is within the 4096 character limit and your API key is valid. Failed requests do not consume your character balance.
What is the rate limit?
The rate limit is 60 requests per minute per key. Before the first top-up, the limit is 10 requests per minute. Exceeding the limit may result in delayed processing or errors. Monitor your usage via the dashboard to stay within limits.
Can I use the OpenAI SDK?
Yes, you can use the official OpenAI SDKs. Change the base_url to https://api.playz555.com/v1 and use your ReadAloud API key. The request shape matches the OpenAI speech endpoint. This allows easy integration into existing projects using standard SDK methods.
Is there a cURL example?
Yes, a ready cURL example is available on the /get-api-key/ page. It demonstrates the correct JSON body structure and headers. Use this example as a starting point for your integration. Replace the placeholder key with your actual API key.
How do I check my balance?
View your balance on the /get-api-key/ page. The dashboard shows your current balance, trial status, characters left, and usage history. Balance does not expire. Top-ups via USDT (TRC-20) are credited automatically within minutes after transfer.
What happens on rate limit?
Requests are processed one after another. If you exceed the rate limit, your request may wait in a queue. Under heavy load, generation may take longer. Ensure you stay within the 60 requests per minute limit for optimal performance.
First request
curl
curl https://api.playz555.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.playz555.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.playz555.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 API access by passing your unique key in the request header. This method keeps your credentials simple and compatible with standard HTTP clients.
Bearer token
Include your key as Authorization: Bearer tts-... in every request. The API validates this token to authorize your account and track usage against your balance.
- Format:
Authorization: Bearer tts-<your_key> - Required for all endpoints
One active key
Each account maintains exactly one active API key at a time. This simplifies security management for indie developers who need a single point of access.
Revoke old key
You can issue a new key at any time. Once issued, the previous key stops working immediately, ensuring old credentials cannot be used.
Endpoints
ReadAloud provides a straightforward REST API designed for indie developers building voice features for educational apps. You interact with three primary endpoints to generate audio, discover available voices, and check model specifications.
Speech generation
Send text to the POST /v1/audio/speech endpoint to receive an audio file. The request body uses the same JSON structure as the OpenAI speech endpoint, allowing you to specify the model, voice, input text, and desired response_format. Text is limited to 4,096 characters per request.
- Endpoint:
POST https://api.playz555.com/v1/audio/speech - Returns: Audio file in the requested format (mp3, wav, opus, flac, pcm)
List voices
Use GET /v1/voices to retrieve available voice presets, supported languages, and formats. This helps you select the appropriate voice for your educational content, such as 'aria' for clear narration or 'atlas' for neutral news-style reading.
- Endpoint:
GET https://api.playz555.com/v1/voices - Returns: List of voices, languages, and formats
List models
Call GET /v1/models to see the available models. Both tts-1 and tts-1-hd use the same engine and pricing, so you can choose based on your quality needs without complexity.
- Endpoint:
GET https://api.playz555.com/v1/models - Returns: Available model identifiers

Request parameters
Configure your synthesis requests by selecting the engine, limiting input length, and choosing a voice. The API accepts either the standard "tts-1" or high-quality "tts-1-hd" model, both using the same underlying engine and pricing structure.
Model selection
Choose between "tts-1" for standard generation or "tts-1-hd" for higher fidelity. Both models use the same engine and are priced identically, allowing you to switch based on your quality needs without cost impact.
Input text limit
Each request supports a maximum of 4096 characters in the input field. This limit includes spaces and punctuation. For longer lessons or audiobooks, split your text into chunks of this size and join the resulting audio files on the client side.
Voice choice
Select one of eight distinct voices from the voice parameter. Female options include aria, nova, luna, and sage, while male voices offer felix, milo, atlas, and orion. Each voice supports all 23 languages, though you should set the language code for non-English Latin text to ensure correct pronunciation.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Response formats
The API returns audio files in the format you specify via the response_format parameter. We support MP3, WAV, FLAC, OPUS, and raw PCM to suit different integration needs, from web playback to local processing.
MP3 output
MP3 is a common format. It offers a good balance between file size and quality, making it ideal for web applications and mobile apps where bandwidth matters. Generated files are ready to play immediately.
WAV output
WAV provides uncompressed, lossless audio. Use this format when you need the highest fidelity for educational content or if your downstream processing tools require standard PCM data without decoding overhead. Files are larger than MP3 but preserve all audio details.
Raw PCM data
Raw PCM returns linear pulse-code modulation data without any container headers. This is useful for low-level audio processing or when you want to build your own audio containers. You receive pure binary audio data that you must handle directly.
Speed control
Adjusting the speed parameter lets you tailor the pacing of generated audio to your specific use case. Whether you are creating slow, clear narration for language learners or quick audio cues for an educational game, the API handles the timing seamlessly without requiring post-processing.
Adjustable speed
The speed field accepts a float value that scales the playback rate. This allows you to speed up conversational content or slow down instructional text for better comprehension, all while maintaining the original voice characteristics.
Range 0.25 to 4.0
You can set the speed between 0.25 (very slow) and 4.0 (very fast). Values outside this range will result in an error. The default speed is 1.0, which represents the natural pacing of the selected voice preset.
Impact on length
Changing the speed directly affects the duration of the resulting audio file. For example, a speed of 2.0 will produce audio that is roughly half the length of the original speech. This helps optimize storage and playback time for students listening on mobile devices.
- Speed 0.5: Audio is twice as long.
- Speed 2.0: Audio is half as long.
- Speed 1.0: Natural pacing, ~25 chars per second.

Error handling
Handle synthesis failures gracefully to avoid wasted credits; failed requests are refunded in full. Always check the HTTP status code before assuming the audio is ready, as network hiccups can occur during generation.
Common errors
Return a 400 if the input exceeds 4096 characters or the voice ID is invalid. Use 401 for incorrect Bearer tokens, and 429 when you hit your quota limits.
Rate limits
New accounts start with a limit of 10 requests per minute. Once you top up, this increases to 60 requests per minute per key. Exceeding this triggers a 429 error until the window resets.
- 10 req/min for new accounts without top-up
- 60 req/min after successful USDT payment
- Limit resets per minute, not per hour
Retry logic
Implement exponential backoff for 429 and 500 errors. Since requests are processed sequentially, short waits between retries prevent queue congestion. Always verify the response status before proceeding to audio playback.
SDK integration
Integrating ReadAloud is straightforward if you already use an OpenAI SDK. Since our API mirrors the official speech endpoint structure, you can reuse your existing code with minimal adjustments. This approach saves time on boilerplate setup and lets you focus on your app’s voice features.
The key change is updating the base URL. Point your client to our API endpoint so all requests route correctly. You can then use standard methods like audio.speech.create with your ReadAloud key.
OpenAI SDK usage
Use an official OpenAI SDK (e.g., Python, Node.js). Pass your API key via the Authorization: Bearer header as usual. The request body structure matches the OpenAI speech endpoint exactly, ensuring compatibility.
- Compatible with official OpenAI SDKs
- Same request body structure
- Standard Bearer token authentication
Base URL change
Update the base URL to https://api.playz555.com/v1. This directs your SDK calls to our infrastructure while keeping your code structure intact. No other endpoint paths need changing for speech generation.
- Base URL: https://api.playz555.com/v1
- Keep standard /v1/audio/speech path
- No code rewrites needed
Python example
Here is a minimal Python snippet using the OpenAI SDK:
```python
from openai import OpenAI
client = OpenAI(base_url="https://api.playz555.com/v1", api_key="tts-your-key-here")
response = client.audio.speech.create(
model="tts-1",
voice="nova",
input="Hello world, this is a test."
)
response.stream_to_file("output.mp3")
``
Replace tts-your-key-here with your API key. Adjust model or voice` as needed.
- Install:
pip install openai - Set
base_urlcorrectly - Stream to file or memory

Rate limits
ReadAloud enforces a rate limit of 60 requests per minute per API key to ensure stable performance for your educational apps. This cap applies to all synthesis requests processed through the API.
60 requests per minute
You can send up to 60 requests per minute once your account is active. This allows indie developers to generate batches of audio files for lessons or exercises without hitting hard limits immediately.
10 requests before top-up
New accounts or those without a top-up are limited to 10 requests per minute. This lower limit helps manage resources while you are testing the API with your free trial credit.
Queue behavior
Requests are processed sequentially. If you exceed the limit or submit many long texts, requests may wait in a queue. Plan your audio generation accordingly to avoid delays in student playback.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Help teachers manage their classrooms by integrating essential tools directly into the learning platform.
23 languages
Any voice speaks any of these languages.
