Cloud TTS API Documentation for Audiobook Production

By Lumivox editorial team · Updated 2026-11-18

This documentation provides the technical reference for the Lumivox text-to-speech API, designed specifically for content creators producing audiobooks and voiceovers. It details the request structure, supported voices, and integration steps needed to convert your kindergarten book manuscripts into high-quality audio files efficiently.

You will find clear examples for authentication, parameter configuration, and error handling using standard tools like cURL or the OpenAI SDK. The guide covers rate limits, language support, and pricing logic so you can reliably generate long texts by splitting them into manageable segments without losing your place in the story.

Cloud TTS API Documentation for Audiobook Production

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

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

Authentication

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

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

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

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

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

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

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

Rate Limits

Error Handling

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

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

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

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. TRON developer hub: TRC-20
  3. Tether (USDT)
  4. FFmpeg documentation
  5. W3C WAI: making audio and video accessible
  6. Creative Commons Attribution 4.0
  7. LibriTTS-R corpus (OpenSLR 141)
  8. openai-node on GitHub
  9. MDN: Web Speech API
  10. IETF RFC 7845: Ogg Opus
  11. OpenAI API reference: create speech
  12. Python documentation

More on this site