Cloud Text-to-Speech API for Indie Developers

By ReadAloud editorial team · Updated 2026-11-18

This guide helps indie developers integrate ReadAloud’s text-to-speech API into educational apps and teacher tools. You will find concrete examples for generating audio from lessons, audiobooks, and exercises, ensuring students can listen anywhere. We cover the essential endpoints, request parameters, and response formats needed to build reliable voice features without unnecessary overhead.

Learn how to authenticate with a single Bearer token, manage rate limits, and adjust speech speed. We provide a Python example using the OpenAI SDK with a custom base URL, so you can start sending text and receiving audio files quickly. This page is designed for developers who need specific, working code and clear explanations of the API’s capabilities and constraints.

Cloud Text-to-Speech API for Indie Developers

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.mp3

Python (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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: 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

Sound wave illustration for: 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
Endpoints

Request parameters

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.
Speed control

Error handling

Sound wave illustration for: 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

Sound wave illustration for: 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_url correctly
  • Stream to file or memory
SDK integration

Rate limits

Sound wave illustration for: 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. MDN: Web Speech API
  3. openai-python on GitHub
  4. curl documentation
  5. ISO 639 language codes
  6. TRON developer hub: TRC-20
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. FFmpeg documentation
  9. OpenAI API reference: create speech
  10. IETF RFC 7845: Ogg Opus
  11. Python documentation
  12. LibriTTS-R corpus (OpenSLR 141)

More on this site