Frequently asked questions
How do I get an API key?
Sign up at /get-api-key/ using Google or email. Accounts created via email start without trial credit, while Google sign-ins receive $0.50 valid for 7 days. You can issue a new key anytime; the old one stops immediately. Keys are per site, so manage them directly on the dashboard.
What is the base URL for the API?
Use https://api.playpx9.com/v1 as your base URL. Send POST requests to /audio/speech. You can also fetch available voices and models via GET /v1/voices and GET /v1/models. This endpoint structure matches the OpenAI API, allowing easy integration with existing tools.
Can I use the OpenAI Python SDK?
Yes. The API accepts the same request shape as OpenAI’s speech endpoint. Configure your OpenAI Python SDK by setting the base_url to https://api.playpx9.com/v1 and providing your Readly API key. This allows you to use official SDKs without custom client logic.
What happens if I exceed rate limits?
You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load a request may wait in a queue. If synthesis fails, the charge is returned in full.
Is the response format binary or JSON?
The /audio/speech endpoint returns the audio file directly in the response body. The request body is JSON. You can choose output formats like mp3, wav, opus, flac, or pcm. The audio file is not stored on our servers after generation.
How do I specify a voice?
Include a voice parameter in your request body. Available presets are aria, nova, luna, sage, felix, milo, atlas, and orion. You can list all voices and their details by calling GET /v1/voices. Each voice supports all 23 supported languages.
Can I change the speed of speech?
Yes. Set the speed parameter between 0.25 and 4.0. Adjusting speed helps tailor the audio to your notification or interface context. The API processes these requests sequentially, so speed changes do not affect queueing behavior.
Does the API support SSML?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You must use plain text input. For precise control, you may need to split text into smaller chunks or adjust voice selection to match the desired tone.
How do I handle long texts?
Split your text into parts of up to 4096 characters. Send each part as a separate request and join the resulting audio files. This ensures compatibility with the character limit. Failed requests are free, so splitting reduces risk of partial loss.
What is the maximum text length?
The maximum input length is 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, you must split the input into multiple requests. Each request is processed sequentially, so plan your batching strategy accordingly.
Is streaming supported?
No. The API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file after synthesis. Typical speed is roughly real-time for long texts, but short phrases may take a few seconds due to queueing.
Can I use multiple voices in one request?
No. Each request accepts only one voice preset. To use multiple voices, you must send separate requests for each voice segment and concatenate the audio files. This approach gives you precise control over the final output structure.
How do I verify my key?
Include your key in the Authorization header as 'Bearer tts-...'. The dashboard at /get-api-key/ displays your active key, balance, and usage. You can verify it by making a test request. If the key is invalid or expired, the request will fail.
What is the difference between tts-1 and tts-1-hd?
Both models use the same engine and price ($0.01 per 1,000 characters). You can use either model identifier in your requests without any difference in cost or output quality.
First request
curl
curl https://api.playpx9.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.playpx9.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.playpx9.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 calls by including your unique key in the Authorization header. Pass it as a Bearer token: Authorization: Bearer tts-<your-key>. This simple header ensures your requests are authenticated and billed to your correct account.
Use Bearer token in Authorization header
Include the header Authorization: Bearer tts-<your-key> in every request. This standard format works seamlessly with the OpenAI SDK and any HTTP client.
One active key per account
Each account maintains a single active API key. If you need to rotate keys for security, issuing a new key immediately invalidates the previous one.
Issue new key to invalidate old one
Generate a new key via your dashboard. The old key stops working instantly, ensuring no overlap or accidental usage after rotation.
Endpoints Overview
The API revolves around three core endpoints. Synthesis uses POST /v1/audio/speech, while GET /v1/voices lists available options and GET /v1/models provides details.
POST /v1/audio/speech for synthesis
Send text and receive audio. This is your primary endpoint for generating speech files.
GET /v1/voices for voice list
Retrieve available voices, languages, formats, and pricing information in a single request.
GET /v1/models for model info
Check model details to confirm supported configurations before synthesizing audio.
Request Parameters
The API accepts a JSON body with three core fields. You must specify the model, the text input, and the desired voice preset. These parameters determine how the audio is generated and which voice performs the narration.
model: tts-1 or tts-1-hd
Choose between "tts-1" and "tts-1-hd". Both models use the same underlying engine and carry identical pricing.
input: text up to 4096 characters
Pass your text in the input field. The API supports up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks and join the resulting audio files.
- Maximum length: 4096 characters
- Spaces and punctuation count as characters
- Split long texts manually for best results
voice: select from 8 presets
Select one of eight voice presets from the voice parameter. Each voice has a distinct tone, from warm narrators to energetic promos. Any voice can speak any of the 23 supported languages.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
- Voices are based on licensed recordings
Response Formats
You choose the audio format via the response_format parameter. Available options are mp3, wav, opus, flac, and pcm. Select mp3 for small file sizes or wav for uncompressed quality. The API returns the raw audio file directly in the response body, ready for immediate playback or storage.
Since the service is a simple REST endpoint, you receive the complete file only after synthesis finishes. There is no streaming or WebSocket support, so partial audio chunks are not available. This design keeps integration predictable and simple for indie developers building SaaS notifications.
mp3, wav, opus, flac, pcm
The response_format field accepts five values: mp3, wav, opus, flac, and pcm. MP3 is ideal for web delivery due to its small size. WAV provides uncompressed quality suitable for local processing. Opus offers high compression efficiency. FLAC ensures lossless quality. PCM returns raw linear audio data.
- Use mp3 for web and mobile apps
- Use wav for high-fidelity requirements
- Use opus for efficient bandwidth usage
- Use flac for lossless archiving
- Use pcm for raw data processing
Audio file returned in response body
The API returns the synthesized audio directly in the response body. You do not need to fetch a URL later. The response headers include Content-Type matching your requested format. This simplifies integration, allowing you to pipe the response directly to a player or file storage system.
No streaming or WebSocket support
The endpoint does not support streaming or WebSocket connections. You receive the entire audio file only after the synthesis completes. This means short phrases may take a few seconds to return, while longer texts take longer still. For real-time partial audio, you would need to implement client-side buffering or split the text manually.
Speed and Language
Adjust playback speed between 0.25x and 4.0x to fit your interface context. Faster speeds suit quick notifications, while slower rates improve clarity for longer passages. This flexibility helps you maintain user engagement without re-generating audio files.
speed: 0.25 to 4.0
Set the speed parameter to control audio tempo. Values range from 0.25 to 4.0. This allows precise tuning for different use cases, from calm storytelling to rapid alerts.
language: optional ISO code
Specify the language parameter using a valid ISO 639-1 code (e.g., en, de, ja). This ensures accurate pronunciation for the 23 supported languages. Explicitly setting the language prevents misinterpretation, especially for non-English Latin script text.
- 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.
Auto-detect if language not set
If you omit the language field, the API attempts to guess it from the text script. Latin script text defaults to English. For other languages using Latin characters, always set the language parameter to ensure correct output.

Rate Limits
Readly API enforces a limit of 60 requests per minute per API key. This applies to all synthesis endpoints and is designed to maintain stability for indie developers integrating TTS into SaaS notifications and interfaces without requiring enterprise-grade infrastructure.
60 requests per minute per key
Each active key allows up to 60 requests per minute. This steady rate is sufficient for most notification workflows and interface updates, ensuring predictable performance without the need for complex queuing logic on your end.
10 requests per minute initially
New accounts start with a lower limit of 10 requests per minute. This prevents sudden bursts from consuming your free trial credit too quickly and helps you test the integration safely before scaling up.
Limits reset after first top-up
The initial 10 req/min limit increases to the full 60 req/min after your first top-up. Since top-ups via USDT on the TRON network (TRC-20) are credited automatically within minutes, you can scale your usage almost immediately after adding funds.
Error Handling
The API returns standard HTTP status codes to indicate success or failure. A 200 OK means your audio is ready. Any 4xx or 5xx error indicates a problem with the request or server.
HTTP status codes for failures
Common errors include 400 Bad Request for invalid parameters, 401 Unauthorized if your key is missing or wrong, and 429 Too Many Requests if you hit the rate limit. Check the response body for specific error messages to debug quickly.
Failed requests are free
If synthesis fails for any reason, you are not charged. The charge is returned in full, so you can retry or adjust your parameters without worrying about wasting credits on broken requests.
Check response for error details
Always inspect the JSON response body for error details. It provides a clear message explaining what went wrong, helping you fix issues like invalid voice IDs or exceeding the 4096-character limit.
OpenAI SDK Integration
Readly API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing integration logic with minimal changes. The primary difference is the base URL, which points to our infrastructure instead of OpenAI's servers.
Change base_url to our API
Update your SDK configuration to use https://api.playpx9.com/v1 as the base URL. This directs all requests to our service while maintaining standard SDK behaviors.
Use official OpenAI SDKs
You can use the official OpenAI SDKs (Python, Node.js, etc.) without installing a custom library. Simply pass your Readly API key as the authorization token.
Same request shape as OpenAI
The request body uses the same fields: model, input, voice, and response_format. This ensures a seamless drop-in replacement for existing TTS integrations.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence.
23 languages
Any voice speaks any of these languages.
