Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.playx333.com/v1. You send POST requests to https://api.playx333.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices are also available at this base URL. This structure allows you to use standard HTTP clients or SDKs by simply pointing them to this address.
How do I authenticate my requests?
Include your API key in the Authorization header as Bearer tts-... . Each account has one active key. If you issue a new key, the old one stops immediately. You can find your key on the /get-api-key/ page after signing up with Google or email.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work perfectly. You just need to change the base_url to https://api.playx333.com/v1 and use your LuminaVoice key. The request shape matches the OpenAI speech endpoint exactly, making integration straightforward for existing OpenAI users without needing a custom client.
What is the maximum character limit?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, you must split the text into chunks of 4096 characters or fewer, generate audio for each part, and then join the resulting audio files.
Does the API support streaming?
No, the API does not support streaming, WebSocket, or real-time partial audio. You send a request and receive the complete audio file in the response. This synchronous approach is suitable for batch processing or pre-generated content rather than live, real-time voice interaction scenarios.
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). If you exceed this, requests may queue or fail. Failed requests are free, so you will not be charged for audio that fails to generate due to limits or errors.
How do I split long texts?
Split your text into parts of up to 4096 characters each. Send each part as a separate POST request to the /v1/audio/speech endpoint. Once you receive the audio files for all parts, join them sequentially to create the final long audio file for your application.
Is there an SDK for mobile apps?
No, there is no official mobile SDK or custom SDK. You should use the OpenAI SDK or plain HTTP requests. Since the API is standard REST, you can integrate it directly into your mobile app using standard networking libraries available in iOS, Android, or cross-platform frameworks like Flutter or React Native.
Can I customize the voice speed?
Yes, you can adjust the speed between 0.25 and 4.0. Include the speed parameter in your JSON request body. This allows you to make voices speak faster or slower to fit your app’s pacing needs, such as speeding up tutorials or slowing down complex instructions.
Do I need to install any libraries?
No specific libraries are required beyond what you already use. If you use the OpenAI SDK, install that. Otherwise, any standard HTTP client can send the JSON POST request. No custom LuminaVoice library is needed, keeping your dependencies minimal and straightforward for mobile app development.
How do I handle audio files?
The API returns the audio file directly in the response body. You can choose formats like mp3, wav, opus, flac, or pcm. Save the response content to a file or stream it directly in your app. The audio is not stored on our servers after the response is sent.
Is the API RESTful?
Yes, the API is RESTful. It uses standard HTTP methods like POST for speech generation and GET for retrieving voices and models. You interact with resources via URLs and JSON payloads, making it easy to integrate with existing mobile app architectures and backend services without custom protocol logic.
What is the response format?
The response contains the audio data in the format you requested: mp3, wav, opus, flac, or pcm. The request body is JSON. The response headers include content-type matching the audio format. You receive the binary audio data directly, ready to be saved or played by your mobile app.
How do I get the list of voices?
Send a GET request to /v1/voices. This endpoint returns details about all 8 available voices, including their names, languages, and supported formats. You can use this data to populate a voice selection menu in your mobile app before making the actual speech synthesis requests.
First request
curl
curl https://api.playx333.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.playx333.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.playx333.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
Create an account on playx333.com using your Google credentials or an email and password. This step activates your access to the API. Google sign-in grants a free trial credit of $0.50 (valid for 7 days), while email accounts start without trial credit.
Sign up on the website
Visit the /get-api-key/ page to register. Google sign-in grants immediate trial credit, while email accounts start without it. The process is quick and requires no credit card.
- Supports Google OAuth and email/password registration
- Instant access to the dashboard
- Free trial credit included for Google users
Find your key in the dashboard
Once logged in, your API key is displayed on the account dashboard. The interface also shows your current balance, trial status, and character usage statistics.
- Key format: tts-...
- Visible alongside balance and usage data
- Ready to copy for cURL or SDK use
Generate new keys anytime
You can generate a new API key at any time from the dashboard. When a new key is issued, the previous one stops working immediately, ensuring secure access control for your mobile app deployments.
- Invalidate old keys instantly
- No limit on key rotations
- One active key per account
First request with cURL
You can test the API immediately using cURL, which requires no library installation. This method sends your text directly to the speech endpoint and returns the audio file for local playback or integration into your mobile app's assets.
The request uses a JSON body. You must include your API key in the Authorization header and specify the model, voice, and input text within the JSON body.
POST request to /v1/audio/speech
Send a POST request to https://api.playx333.com/v1/audio/speech. Include your bearer token in the Authorization header to authenticate the request.
JSON body with model and input
The request body must be valid JSON. Specify the model (tts-1 or tts-1-hd), the voice preset (e.g., aria, nova), and the input text up to 4,096 characters.
- "model": "tts-1"
- "voice": "nova"
- "input": "Hello world"
- "response_format": "mp3"
Receive audio file in response
Upon success, the API returns the audio file directly in the response body. The file format matches your specified response_format (mp3, wav, opus, flac, or pcm). Failed requests return no charge.
Integration with OpenAI SDK
LuminaVoice uses the same request shape as the OpenAI speech endpoint. You can use the official OpenAI SDKs by simply changing the base_url to https://api.playx333.com/v1 and providing your API key. This allows mobile app teams to test voices in Arabic, Hindi, Spanish, and 20 other languages with minimal code changes.
The SDK handles the HTTP requests automatically. You pass your API key as a Bearer token in the authorization header. This setup works for both Python and JavaScript SDKs, making integration straightforward for startups building international mobile releases.
Change base_url to our endpoint
Set the base_url configuration in your OpenAI SDK client to https://api.playx333.com/v1. This directs all API calls to LuminaVoice’s infrastructure while maintaining the standard request structure.
You do not need to rewrite your HTTP logic. The endpoint POST /v1/audio/speech accepts the same JSON body as OpenAI’s speech endpoint.
- Base URL: https://api.playx333.com/v1
- Endpoint: POST /v1/audio/speech
- Body: JSON with model, input, voice
Use official OpenAI SDKs
Use the official OpenAI SDKs for your preferred language. They handle serialization and retries efficiently.
Since the request shape is identical, you can use the same code structure for voice synthesis in your mobile app backend.
Pass your API key as Bearer token
Include your API key in the Authorization header as Bearer tts-your-key-here.
One active key per account ensures consistent billing and rate limiting across your mobile app’s usage.
Request parameters
Configure the request body with the selected model, input text, and voice preset. The API accepts standard JSON fields to synthesize audio files directly.
Model: tts-1 or tts-1-hd
Select "tts-1" for standard quality or "tts-1-hd" for high-definition audio. Both models use the same underlying engine and pricing structure.
Input: text up to 4,096 characters
Pass your localized string in the input field. The limit is 4,096 characters per request, including spaces and punctuation. Split longer texts into chunks and join the resulting audio files.
Voice: one of 8 presets
Choose from eight distinct voices for your app interface. Options include female presets like aria and nova, or male voices such as felix and atlas. Each voice supports all 23 available languages.
- Aria: warm, clear narrator
- Felix: energetic, promo
- Milo: friendly, conversational
- Atlas: neutral, news
- Orion: deep, documentary
- Luna: soft, storytelling
Response formats
Select your preferred audio format via the response_format field. We support MP3, WAV, Opus, FLAC, and PCM, allowing you to optimize file sizes and compatibility for your specific mobile app architecture without additional conversion steps.
MP3, WAV, Opus, FLAC, PCM
Choose the format that best fits your delivery pipeline. MP3 offers efficient compression for general use, while WAV and FLAC provide lossless quality. Opus is ideal for low-bandwidth scenarios, and PCM provides raw uncompressed audio data.
Audio file in response body
The synthesized audio is returned directly in the HTTP response body as a binary file. You can stream this data immediately to your application's local storage or playback buffer, ensuring a seamless user experience.
No streaming support
This API does not support streaming or WebSocket connections for partial audio chunks. The entire audio file is generated and returned once synthesis is complete, which typically takes a few seconds for short phrases.

Rate limits
API usage is capped to ensure fair access across all developers. Each API key supports a maximum of 60 requests per minute, which is sufficient for most mobile app testing workflows. This limit applies per key, allowing you to scale by generating additional keys if needed.
Requests are processed sequentially, so under heavy load, a request may wait in a queue. This ensures stability but means short phrases may take a few seconds to generate. Plan your integration accordingly to avoid unnecessary delays during peak usage.
60 requests per minute per key
The standard rate limit allows 60 requests per minute for each active API key. This is adequate for typical development and small-scale production use cases. If you need higher throughput, consider issuing a new key from your dashboard.
10 requests per minute initially
When you first sign up, your key starts with a reduced limit of 10 requests per minute. This helps prevent accidental abuse during the trial period. You can quickly increase this limit by adding funds to your account.
Limit increases after top-up
Once you top up your balance with USDT on the TRON network (TRC-20), your rate limit automatically increases to 60 requests per minute. Credits are credited within minutes of transfer, allowing you to resume testing or production immediately without waiting for manual verification.
Handling errors
When synthesis fails, you pay nothing. The API returns a non-200 status code and your balance remains unchanged, so failed attempts do not consume your character credits. This protects your budget during testing phases with new voices or languages.
Failed requests are free
If the server cannot process your text due to invalid input or temporary backend issues, the request is marked as failed. You receive a standard HTTP error response, and no charge is applied to your account.
Check status codes in response
Monitor the HTTP status code in your response header. A 200 OK indicates success and includes the audio data. Any 4xx or 5xx code signals an error that requires attention before retrying.
- 400: Invalid request body or parameters
- 401: Unauthorized (check your API key)
- 429: Rate limit exceeded
- 500: Internal server error
Retry logic for temporary issues
Implement exponential backoff for 5xx errors. Since requests are processed sequentially, high load may cause temporary delays. Wait briefly before retrying to avoid overwhelming the queue. For 429 errors, wait until your rate limit resets or top up your balance to increase the limit.
Additional endpoints
The API provides two additional endpoints to help you inspect available resources before making synthesis requests. These endpoints allow your application to dynamically discover supported voices and models without hardcoding values.
GET /v1/voices for voice list
Retrieve the full list of available voices, including their IDs, genders, and supported languages. Each voice is based on licensed recordings and can speak any of the 23 supported languages.
- Returns voice ID, gender, and language support
- Useful for populating UI dropdowns in mobile apps
GET /v1/models for model info
Fetch details about the TTS models, including their IDs and pricing tiers. Both tts-1 and tts-1-hd use the same engine and price, but may differ in output format options.
- Lists model IDs and capabilities
- Confirms pricing structure for each model
List languages and formats
Retrieve the complete list of supported languages and audio output formats. Languages include Arabic, Hindi, Spanish, and 20 others. Formats include mp3, wav, opus, flac, and pcm.
- Lists all 23 supported languages
- Lists available audio output formats
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Craft intuitive mobile applications that captivate early adopters and drive rapid user acquisition.
23 languages
Any voice speaks any of these languages.
