Frequently asked questions
What is the base URL for the API?
The API base URL is https://api.getx99.com/v1. You send POST requests to https://api.getx99.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base path.
How do I authenticate with the API?
Include your API key in the request header as Authorization: Bearer tts-... . Each account has one active key. If you need a new key, you can issue it from your dashboard, and the old key stops working immediately. Ensure your key is valid before sending requests.
Can I use the OpenAI SDK?
Yes, the official OpenAI SDKs work by changing the base_url to https://api.getx99.com/v1 and using your site's key. The request shape matches the OpenAI speech endpoint.
What is the maximum text length?
Each request supports up to 4096 characters in the input field. Spaces and punctuation count toward this limit. For longer texts, split them into parts of 4096 characters or less and join the resulting audio files. This ensures efficient processing and avoids payload size issues.
How do I specify the output format?
Set the response_format field in the JSON body to mp3, wav, opus, flac, or pcm. These formats are available for all voices. Choose the format that best fits your playback environment or editing workflow. The API returns the audio file directly in the specified format.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with 10 requests per minute. Failed requests are free, so you are not charged for audio that does not generate successfully.
Can I change the speed of the audio?
Yes, set the speed field between 0.25 and 4.0. This adjusts the playback rate of the generated speech. Lower values slow down the audio, while higher values speed it up, useful for different narration styles.
How do I handle long texts?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate request. Then, join the resulting audio files. This approach handles books or long scripts efficiently. The API does not store the audio, so you manage the final assembly.
Is the audio format MP3 only?
No, you can choose from mp3, wav, opus, flac, or pcm. MP3 is just one option. Select the format that suits your needs. All voices support all these formats. The choice affects file size and compatibility with your playback devices or editing software.
How do I get the list of voices?
Send a GET request to /v1/voices. This endpoint returns available voices, languages, formats, and price. You can also check /v1/models. Use this information to select the right voice for your content. The response includes details needed for your API calls.
Can I use custom voices?
No, the API offers 8 preset voices: aria, nova, luna, sage, felix, milo, atlas, and orion. There is no custom voice cloning or uploading your own voice. These presets cover various tones and languages. You cannot create or upload unique voice models for your content.
Does the API support SSML?
No, the API does not support SSML. You cannot use phoneme dictionaries or custom pronunciation lexicons. Input is plain text. If you need specific pronunciation, you may need to adjust the text manually. The API focuses on simple text input for broad compatibility.
What is the typical response time?
Long texts generate at roughly real-time speed, about 25 characters per second. Short phrases take a few seconds. Requests are processed sequentially, so under load, you may experience queue delays. This timing ensures consistent quality without overloading the synthesis engine.
How do I issue a new API key?
Go to the /get-api-key/ page on the site. You can issue a new key at any time. The old key stops working immediately when the new one is active.
First request
curl
curl https://api.getx99.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.getx99.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.getx99.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
To access the Lumivox API, include your unique API key in the Authorization header of every request. This bearer token authenticates your account and tracks usage against your balance. Keep this key secure, as it is the sole credential for generating audio files.
Bearer token in header
Include the header Authorization: Bearer tts-... in your HTTP requests. The API uses this token to verify your identity and deduct character counts from your account balance.
One active key per account
Each account holds exactly one active API key. If you suspect a leak or need to rotate credentials, you can issue a new key at any time via your dashboard.
Issue new key to revoke old
Generating a new key immediately invalidates the previous one. The old key stops working at once, ensuring only your current credential remains valid for API calls.
Endpoint Overview
The Lumivox API provides three primary endpoints for audiobook production. Use POST /v1/audio/speech to generate audio from text. Access GET /v1/voices to list available presets and GET /v1/models to view engine details.
POST /v1/audio/speech
This endpoint accepts text and returns an audio file. Send a JSON body with your model, input text, and voice selection. The API handles the synthesis and returns the binary audio data directly in the response.
GET /v1/voices
Retrieve the list of eight available voice presets. This endpoint also provides details on supported languages and audio formats, helping you select the right narrator for your kindergarten books.
GET /v1/models
View the available models, including tts-1 and tts-1-hd. Both models use the same engine and pricing, allowing you to switch based on your quality needs without changing your integration logic.
Request Parameters
The API accepts text input up to 4,096 characters per request. For longer kindergarten books, split the text into chunks and join the resulting audio files automatically. Each request is processed sequentially, so under load, synthesis may wait in a queue before generating audio.
Model: tts-1 or tts-1-hd
Select "tts-1" or "tts-1-hd" for the same engine and price. Both models generate audio at roughly real-time speed (25 characters per second). The choice affects file format quality but not the underlying synthesis engine or cost.
Input text up to 4096 chars
Pass your manuscript text in the input field. Spaces and punctuation count toward the 4,096 character limit. If your story exceeds this length, split it into parts and concatenate the returned audio files.
Voice selection from 8 presets
Choose from eight licensed voices based on LibriTTS-R and LibriVox recordings. Options include warm narrators like Aria and Luna, or friendly conversational styles like Milo. Each voice supports all 23 languages; set the language parameter to ensure correct pronunciation for non-English texts.
Voices carry an inaudible watermark marking them as synthetic speech. No custom cloning or emotion tags are available.
- Aria: warm, clear narrator
- Nova: bright, upbeat
- Luna: soft, storytelling
- Sage: calm, instructional
- Felix: energetic, promo
- Milo: friendly, conversational
Response Format
The API response body contains the synthesized audio file directly, allowing you to save or play it immediately. Each request generates a single audio file corresponding to the input text chunk. For longer texts, you must split the content into segments of up to 4096 characters and join the resulting audio files yourself to create the final audiobook. This ensures efficient processing and keeps individual request sizes manageable.
Generated audio is not stored on our servers; it is returned in the response and discarded. Only request metadata like time and character count is kept for billing purposes. This means you are responsible for storing the final audio files if you need to archive them for your self-published titles.
Audio file in response
The API returns the audio file directly in the response body. You do not need to poll for a file ID or download it from a separate URL. This direct delivery simplifies integration, allowing you to pipe the output straight to a file or audio player.
For audiobook production, this means your workflow involves sending text chunks and receiving the audio segments sequentially. You can then concatenate these segments using standard audio libraries to create a complete chapter or book.
MP3, WAV, OPUS, FLAC, PCM
You can choose the output format using the response_format parameter. Supported formats include MP3, WAV, OPUS, FLAC, and PCM. MP3 is suitable for web distribution, while WAV and FLAC offer lossless quality for archival. PCM provides raw audio data for further processing.
Selecting the right format depends on your distribution needs. MP3 and OPUS are compressed and ideal for streaming or smaller file sizes. WAV and FLAC preserve audio quality without loss. PCM is uncompressed raw audio, useful for specific editing workflows.
- MP3: Compressed, good for web and mobile
- WAV: Uncompressed, high quality
- OPUS: Efficient compression, good for streaming
- FLAC: Lossless compression
- PCM: Raw uncompressed audio
Binary audio data
The response contains binary audio data. You can save it to disk using standard binary write operations. Since the audio is returned as binary, you can save it to disk using standard binary write operations. This allows you to store the audio files locally for your audiobook projects without needing a database or cloud storage for the audio files themselves.
When processing the response, ensure your code handles binary data correctly. Most programming languages have libraries to write binary data to files. This ensures the audio file is saved correctly and can be played by standard audio players.
Rate Limits
Your API key allows 60 requests per minute once funded. This limit applies per key, so generating long audiobooks requires splitting text into 4,096-character segments and processing them sequentially.
60 requests per minute
The standard limit is 60 requests per minute per key. Since each request handles up to 4,096 characters, this throughput supports roughly 250,000 characters per minute during sustained usage.
10 requests before first top-up
New accounts start with a lower limit of 10 requests per minute. You can increase this immediately by topping up your balance via USDT (TRC-20). The limit resets to 60 requests per minute once the transfer is credited.
Queued under load
Requests are processed sequentially. If many users are generating audio simultaneously, your request may wait in a queue. Expect slight delays during peak times, but failed requests remain free.

Error Handling
When a request fails, the API returns standard HTTP status codes to indicate the nature of the issue. A 4xx code typically signals a problem with your request, such as an invalid voice ID or missing parameters. A 5xx code indicates a temporary server-side issue, often due to high load or queueing delays during peak production hours.
4xx and 5xx status codes
Common 4xx errors include 400 Bad Request (invalid JSON or model) and 401 Unauthorized (invalid or revoked API key). If you receive a 429 Too Many Requests, your key has exceeded the rate limit. Wait briefly.
- 400: Invalid input or model parameter
- 401: Invalid or expired API key
- 429: Rate limit exceeded
- 500: Internal server error
Error message in JSON
All error responses include a JSON body with a clear error message and code. This structure allows you to programmatically handle failures in your audiobook generation pipeline. Check the error code to determine if you need to adjust your text length, switch voices, or retry the request.
Failed requests are free
If synthesis fails due to a server error or rate limit, you are not charged. The full amount is returned to your balance. This ensures you only pay for successfully generated audio files, protecting your budget during long audiobook production runs.
Language Support
The API supports 23 languages including English, Spanish, German, French, Japanese, and Arabic. You can explicitly define the language using an ISO code in the request body to ensure precise synthesis, or omit it to rely on automatic detection based on the text script.
Optional ISO language code
Include the language field with a valid ISO 639-1 code (e.g., "en", "es", "de") to guide the engine. This is recommended for consistent results, especially when mixing languages or using less common scripts within a single request.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Auto-detect for Latin script
If you do not set the language field, the system guesses the language from the script. Text in Latin script defaults to English. This works well for straightforward English content but may misinterpret mixed-language texts.
Set language for non-English
For non-English text using Latin script (e.g., German, French, or Spanish), you must set the language parameter. Without this, the engine will assume English, resulting in an incorrect accent or pronunciation for your audiobook narration.
- Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali
Code Examples
Use the following examples to integrate Lumivox into your audiobook workflow. The API accepts standard JSON payloads, allowing you to generate audio files directly from your writing or publishing scripts.
cURL command example
Generate a speech file using the command line. Replace YOUR_API_KEY with your key from the dashboard.
- curl -X POST https://api.getx99.com/v1/audio/speech \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "The quick brown fox jumps over the lazy dog.", "voice": "aria", "response_format": "mp3"}' \ -o output.mp3
OpenAI SDK with base_url
The OpenAI Python SDK works by pointing it to our endpoint. This allows you to use familiar libraries for your self-published titles.
- from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="https://api.getx99.com/v1" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Once upon a time in a small village...", response_format="mp3" ) audio.stream_to_file("audiobook.mp3")
Python request example
For full control, use the requests library. Split long texts into chunks of 4096 characters before sending.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Male voices offer distinct tonal qualities for different narrative needs.
23 languages
Any voice speaks any of these languages.
