API Documentation for Text-to-Speech Integration

By LuminaRead editorial team · Updated 2026-11-18

This documentation provides everything you need to integrate LuminaRead’s text-to-speech API into your product’s accessibility workflow. You will learn how to generate natural, compliant audio for users with dyslexia and visual impairments using simple HTTP requests or the OpenAI SDK. We cover authentication, parameter configuration, and error handling with concrete examples.

Designed for developers building inclusive digital experiences, this guide explains how to handle long texts, manage rate limits, and choose the right audio format. You will find ready-to-use cURL commands and clear explanations of voice presets and pricing. Follow these steps to turn any text into clear, synthetic speech efficiently.

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

Python (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
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

Get Your API Key

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

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

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

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

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

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 POST method to the /v1/audio/speech endpoint.
  • Set Content-Type: application/json in 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

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

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

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

Sound wave illustration for: 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 model is "tts-1" or "tts-1-hd".
  • Verify voice is one of the 8 supported presets.
  • Ensure input does 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

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

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

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. openai-python on GitHub
  3. Python documentation
  4. LibriTTS-R corpus (OpenSLR 141)
  5. IETF RFC 7845: Ogg Opus
  6. LibriVox public-domain audiobooks
  7. curl documentation
  8. TRON developer hub: TRC-20
  9. Node.js documentation
  10. Tether (USDT)
  11. openai-node on GitHub
  12. W3C WAI: making audio and video accessible

More on this site