Frequently asked questions
Do I need to install a specific SDK?
No. You can use the official OpenAI SDKs by changing the base_url to https://api.playmx52.com/v1 and using your API key. Alternatively, you may use plain HTTP requests. We do not provide an official SDK of our own, so standard HTTP libraries work perfectly for integration.
Is the API compatible with Python?
Yes. Since the API follows the same request shape as the OpenAI speech endpoint, you can use the official OpenAI Python SDK. Simply update the base_url to https://api.playmx52.com/v1 and pass your tts-... key. Standard HTTP libraries also work seamlessly for all Python environments.
How do I handle Japanese characters in JSON?
Include the text in the input field as standard UTF-8 JSON. Ensure the language field is set to ja to ensure correct pronunciation, as the API does not always guess non-Latin scripts accurately. The API handles the character encoding automatically within the JSON body.
Can I stream audio as it generates?
No. The API does not support streaming, WebSockets, or real-time partial audio. You send a POST request and receive the complete audio file in the response. For long texts, split the input into parts of up to 4096 characters and join the resulting audio files.
What is the maximum speed setting?
The maximum speed setting is 4.0. You can adjust the speed parameter between 0.25 and 4.0 to control the playback rate. This allows you to customize the speech pace for different accessibility needs, such as slower speeds for users with dyslexia or faster rates for efficiency.
Does the API support SSML tags?
No. The API does not support SSML tags, phoneme dictionaries, or custom pronunciation lexicons. You control speech characteristics using the voice preset, speed parameter, and optional language code. For precise control, you must manage text segmentation and audio joining in your application logic.
How do I know if a request failed?
Check the HTTP status code in the response. If synthesis fails, the charge is returned in full, so you are not billed for the attempt. Failed requests do not consume your character allowance. Ensure your client handles standard HTTP error codes to detect and retry failed requests appropriately.
Can I use multiple voices in one request?
No. Each request accepts only one voice parameter. To use multiple voices, you must send separate requests for each segment of text. You can then join the resulting audio files in your application. This ensures each segment uses the correct voice preset as specified.
Is the audio returned as a URL or binary?
The audio is returned directly in the response body, not as a URL. The generated audio is not stored on our servers after the response is sent. You must handle the binary data or audio file format (mp3, wav, opus, flac, pcm) immediately upon receiving the response.
Do I need to cache the audio files?
Caching is up to you since the audio is not stored on our servers. You can cache the generated files locally or in your storage to avoid re-synthesizing identical text. This is efficient for static content, but for dynamic text, you must generate audio on each request.
How do I handle rate limit errors?
The limit is 60 requests per minute per key. If you exceed this, you will receive a rate limit error. Implement exponential backoff in your client to retry after a short delay. New accounts start with a 10 requests per minute limit until the first top-up is processed.
Is there a sandbox environment?
No. There is no separate sandbox environment. You use the same production endpoint https://api.playmx52.com/v1 for testing. You can use your free trial credit of $0.50 (if applicable) to test integration. Failed requests are free, allowing you to test error handling without consuming your balance.
Can I use the API with React Native?
Yes. Since the API uses standard HTTP POST requests with JSON bodies, it works with any HTTP client. You can use standard fetch or axios libraries in React Native. Ensure you handle the binary audio response appropriately for playback within your mobile application environment.
How do I rotate my API key?
You can issue a new key at any time from your account dashboard. The new key becomes active immediately, and the old one stops working at once. This allows for seamless rotation without downtime. You can manage your active key directly from the /get-api-key/ page.
First request
curl
curl https://api.playmx52.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.playmx52.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.playmx52.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 |
Get Your API Key
LuminaRead provides a straightforward path to generating accessible audio for your users. Begin by creating an account on playmx52.com using either Google or a standard email and password. This account tracks your usage and billing specifically for this storefront.
Sign Up on the Site
Visit the /get-api-key/ page to register. Your account is tied to this specific site domain, ensuring clear separation if you use other network stores. Once registered, you can immediately view your dashboard.
Generate Key via Google
Signing in with Google grants you a $0.50 free trial credit, valid for seven days. This allows you to test the API without immediate payment. The key appears instantly in your dashboard, ready for the first request.
- Google sign-in includes $0.50 trial credit
- Email/password accounts start without trial credit
- Key is visible immediately after registration
Rotate Keys Anytime
You maintain one active key per account. If you suspect exposure or simply want fresh credentials, you can issue a new key at any time. The old key stops working immediately, ensuring clean security without downtime.
First Request with cURL
Once you have your API key, you can test the synthesis engine immediately using a standard HTTP client. The API accepts a simple JSON payload and returns a binary audio file, making integration straightforward for any backend service.
Start by sending a POST request to the speech endpoint. This basic example demonstrates how to generate a short audio clip using the default settings, which is ideal for verifying your key and network connectivity before building complex workflows.
Basic JSON Body
The request body is a standard JSON object containing the text to be spoken and the configuration parameters. You must include the text input and select a voice model. The API processes this data and returns the synthesized audio in the response body.
Keep the payload concise. For simple tests, a short phrase is sufficient. The system handles the encoding and formatting automatically, so you only need to focus on the text content and the desired audio properties.
- Use
POSTmethod to the/v1/audio/speechendpoint. - Set
Content-Type: application/jsonin your headers. - Ensure the text does not exceed 4096 characters for a single request.
Required Fields
To generate audio, you must provide the model and input fields. The model can be either tts-1 or tts-1-hd, both using the same engine. The input field contains the actual text string you want converted to speech.
You also need to specify a voice from the eight available presets. If you omit the language field, the system attempts to guess it from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate pronunciation for non-English content.
Response Format
On success, the API returns a 200 OK status code with the audio file directly in the response body. The format matches your response_format parameter, such as MP3 or WAV. You can save this binary data to a file or stream it directly.
If the request fails, you will receive an error code and a JSON object describing the issue. Common errors include invalid parameters or insufficient balance. Failed requests do not incur charges, so you can safely retry them.
Using the OpenAI SDK
The OpenAI SDKs work seamlessly with our API by simply changing the base_url. This allows your existing code to generate speech without rewriting the core logic. You only need to update the endpoint to https://api.playmx52.com/v1.
The request method remains POST, and the JSON structure is identical to the standard speech endpoint. This consistency means your product team can integrate natural speech for users with dyslexia quickly, using tools they already know.
Change Base URL
Point your SDK client to our API base: https://api.playmx52.com/v1. This directs all calls to our TTS endpoint while keeping the SDK’s request logic intact.
Keep Same Method
Use the standard POST method with the /audio/speech path. The JSON body requires model, input, voice, and response_format. No extra parameters are needed for basic usage.
Authentication Header
Include your key in the Authorization header as Bearer tts-your-key-here. Ensure the key starts with tts-. Each account has one active key; rotate it anytime via the dashboard.
Failed requests do not consume credit, so you can safely retry without worrying about unexpected charges.
Supported Parameters
The API accepts four primary parameters to tailor audio output: model, voice, speed, and response_format. While model selects the engine and response_format determines the file type, voice and speed offer direct control over the listening experience.
Model Selection
Choose between tts-1 for standard quality and tts-1-hd for higher fidelity. Both models use the same engine and pricing, so selection depends on your preference for audio clarity versus processing speed.
Voice Presets
Select from eight distinct voice presets to match your content’s tone. Female voices include Aria (warm narrator), Nova (bright), Luna (soft storyteller), and Sage (calm instructor). Male options include Felix (energetic), Milo (friendly), Atlas (neutral news), and Orion (deep documentary).
- Aria, Nova, Luna, Sage
- Felix, Milo, Atlas, Orion
Speed Control
Adjust the playback rate between 0.25 and 4.0. Slower speeds aid comprehension for users with dyslexia, while faster rates suit quick scanning.
Audio Formats
Choose the format that best fits your application’s delivery needs. LuminaRead supports MP3, WAV, OPUS, FLAC, and PCM, allowing you to balance file size, quality, and compatibility for accessible digital experiences.
All formats are generated from the same engine. You can switch formats without re-entering your text, ensuring consistent voice output across different player capabilities.
MP3 for Web
MP3 is the standard for web delivery. It offers a good balance between file size and audio quality, making it ideal for most browsers and mobile devices.
Use MP3 when you need broad compatibility without significant storage overhead. It works with standard HTML5 audio players.
- Small file size for faster loading
- Universal browser support
- Ideal for streaming web content
WAV for Quality
WAV provides uncompressed, lossless audio. It is suitable for high-fidelity applications where audio quality is prioritized over file size.
Choose WAV for archival purposes or when processing the audio further in your pipeline. It preserves the audio data.
- Lossless quality
- No compression artifacts
- Best for post-processing
OPUS for Efficiency
OPUS delivers high-quality audio at very low bitrates. It is excellent for mobile data saving and low-bandwidth environments.
Use OPUS when you need to minimize data usage while maintaining clear, natural speech. It is supported in modern web and mobile applications.
- High efficiency at low bitrates
- Low data consumption
- Modern web support
Handling Errors
When the API rejects a request, it returns a specific error code to help you fix the issue quickly. Most errors are due to incorrect input formatting or missing required fields in the JSON body.
These responses include details about what went wrong, allowing you to adjust your integration.
400 Bad Request
A 400 error occurs when the request body is malformed or contains invalid values. Common causes include exceeding the 4096 character limit for the input field, providing an invalid voice name, or setting the speed outside the 0.25–4.0 range. Ensure your JSON structure matches the required schema exactly.
- Check that
modelis "tts-1" or "tts-1-hd". - Verify
voiceis one of the 8 supported presets. - Ensure
inputdoes not exceed 4096 characters.
401 Unauthorized
This error indicates that your API key is missing, invalid, or has been revoked. If you rotated your key via the dashboard, the old key stops immediately. Ensure your Authorization header uses the correct Bearer format with your active key.
- Verify the key starts with
tts-. - Check for trailing spaces in the key string.
- Confirm the key is active on /get-api-key/.
429 Rate Limit
If you exceed 60 requests per minute, the API returns a 429 error. New accounts without top-ups are limited to 10 requests per minute. Implement exponential backoff in your code to handle retries gracefully without overwhelming the endpoint.
- Standard limit: 60 requests/minute.
- Initial limit: 10 requests/minute.
- Retries succeed once the window resets.
Rate Limits Explained
Rate limits protect the API's stability during high traffic. Each API key is capped at 60 requests per minute, ensuring consistent performance for your product team's integration. This limit applies per key, so rotating keys can effectively double your throughput if needed.
Understanding these constraints helps you plan your audio generation workflows efficiently. By monitoring your usage dashboard, you can anticipate peak times and adjust your request patterns to avoid delays.
60 Requests Per Minute
Each API key allows up to 60 requests per minute. This limit applies to the speech endpoint. If you exceed this, subsequent requests will be rejected until the window resets.
For new accounts, the limit is lower at 10 requests per minute until the first top-up is completed. This helps manage initial load while you integrate the API.
- Limit is per API key, not per account
- Resets every 60 seconds
- Exceeding limits returns a 429 status code
Queue Behavior
Requests are processed one after another. If the queue is full, additional requests may experience slight delays.
Longer texts take more time to generate, so they may hold up the queue. Plan your requests accordingly to minimize wait times for time-sensitive audio generation.
- Requests are processed in order
- Longer texts may cause slight delays
- Queues reset every 60 seconds
Burst Handling
For bursty traffic, consider using multiple API keys to distribute the load. This allows you to exceed the per-key limit while staying within the overall rate.
Rotate keys periodically to maintain high throughput. Each key has its own rate limit, so using multiple keys effectively multiplies your capacity.
- Use multiple keys for higher throughput
- Rotate keys to maintain capacity
- Monitor usage to avoid bottlenecks
Long Text Processing
The API accepts input text up to 4,096 characters per request. For longer content, split your text into chunks of this size and send them sequentially. The service processes requests one after another, so longer texts may queue under load.
4096 Character Limit
Each POST request is capped at 4,096 characters. Exceeding this limit returns a 400 Bad Request error. Ensure your client code validates text length before transmission to avoid silent failures or truncated audio.
Split and Join Audio
To handle books or long articles, divide the text into 4,096-character segments. Generate audio for each segment individually, then concatenate the resulting files on your end.
- Split text into 4,096-char blocks
- Send each block via POST
- Concatenate output audio files
Character Counting
Spaces, punctuation, and special characters all count toward the 4,096 limit. Since billing is per character, accurate counting helps predict costs. Roughly, 25 characters generate one second of audio.
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.