API Documentation for Indie Developers: TTS Integration Guide

By Playr77 editorial team · Updated 2026-11-18

This documentation provides the technical specifications for integrating Lumivoice’s text-to-speech API into your applications. It covers authentication, endpoint definitions, request parameters, and response formats, enabling seamless deployment for indie developers and no-code users who require consistent audio generation without complex infrastructure.

The guide includes concrete cURL commands and code examples using the official OpenAI SDK, allowing you to generate speech with eight licensed voices in 23 languages. You will find precise details on pricing, rate limits, and error handling to ensure reliable integration. All information is specific to the API available at https://api.playr77.com/v1.

API Documentation for Indie Developers: TTS Integration Guide

Frequently asked questions

How do I get my API key?

Sign up at https://playr77.com/get-api-key/ using Google or email. The dashboard displays your active key, balance, and usage statistics. You can issue a new key at any time; the previous key stops immediately upon rotation.

Can I use the OpenAI Python SDK?

Yes. The API uses the same request shape as OpenAI’s speech endpoint. Configure the OpenAI SDK’s base_url to https://api.playr77.com/v1 and provide your Lumivoice key. The official SDKs work without modification.

What is the base URL for the API?

The base URL is https://api.playr77.com/v1. Send POST requests to /v1/audio/speech for synthesis. Use GET /v1/voices to list available voices and GET /v1/models to check model status.

Does the API support streaming audio?

No. The API does not support streaming, WebSocket, or real-time partial audio. You receive the complete audio file in the response body after synthesis finishes. Requests are processed sequentially, so long texts may queue.

What happens if the API is rate limited?

You are limited to 60 requests per minute per key (10 before the first top-up). Excess requests may wait in a queue. Failed requests are free and do not consume your character balance or count toward limits.

Can I use multiple voices in one request?

No. Each request accepts a single voice parameter. To use different voices, send separate requests for each segment. You must join the resulting audio files manually or via a post-processing step.

How do I specify the language?

Include the optional language field with an ISO code (e.g., de, fr). If omitted, the system guesses the language from the script. Latin script defaults to English, so explicitly set the language for other Latin texts.

Is the response format configurable?

Yes. Specify response_format as mp3, wav, opus, flac, or pcm. The default is mp3. The API returns the audio file directly in the response body according to your selected format.

What is the maximum input length?

The maximum input length is 4096 characters per request. Spaces and punctuation count toward this limit. Longer texts must be split into chunks of 4096 characters or fewer before sending individual requests.

How do I handle long texts?

Split your text into parts of up to 4096 characters. Send each part as a separate request. Receive the individual audio files and join them using your preferred audio processing tool or library.

Are there any SDK-specific quirks?

No. Since the API mimics the OpenAI speech endpoint, standard OpenAI SDK behavior applies. Ensure you update the base_url and use your Lumivoice key. No additional quirks or custom parameters are required for integration.

How do I rotate my API key?

Issue a new key from your dashboard at any time. The new key becomes active immediately, and the old key stops working at once. This allows seamless rotation without downtime for your applications.

What is the difference between tts-1 and tts-1-hd?

There is no difference. Both tts-1 and tts-1-hd use the same engine and have the same price. You can use either model identifier interchangeably for synthesis requests without affecting cost or quality.

Can I use the API from a browser?

Yes. You can send requests directly from a browser using JavaScript or tools like cURL. Ensure you protect your API key if exposing it client-side, as there is no built-in key management for browsers.

First request

curl

curl https://api.playr77.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.playr77.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.playr77.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

Authentication relies on a single active API key per account. You generate this key on the /get-api-key/ page after signing in via Google or email. The system issues one token that authorizes all requests to the API base URL.

API Key Generation

API Key Generation

Visit the get-api-key/ dashboard to view or create your credential. Accounts created with email and password do not receive the free trial credit, whereas Google sign-ins include an initial $0.50 balance. Only one key is active at any time.

  • Generate a new key anytime from the dashboard.
  • Existing keys become inactive immediately upon rotation.
  • Keys start with the prefix 'tts-'.

Bearer Token Format

Bearer Token Format

Include your key in the HTTP header as a Bearer token. The format is strictly Authorization: Bearer tts-<your_key>. Ensure no extra spaces or characters are included in the token value to avoid 401 Unauthorized errors.

Key Rotation Process

You can issue a new key at any time via the dashboard. The old key stops working immediately when the new one is created. This allows zero-downtime rotation if you need to revoke a compromised token.

Endpoints

Sound wave illustration for: Endpoints

The API exposes three primary endpoints for text-to-speech synthesis and metadata retrieval. The core synthesis endpoint accepts POST requests with JSON bodies, while GET endpoints provide available voices and model details.

All endpoints require authentication via a Bearer token in the Authorization header. Requests are processed sequentially, so high concurrency may introduce queue delays.

POST /v1/audio/speech

Accepts text input up to 4096 characters and returns synthesized audio in the specified format. Supports model selection (tts-1 or tts-1-hd), voice presets, speed adjustments, and optional language codes.

  • Method: POST
  • Content-Type: application/json
  • Response: Binary audio file or JSON error

GET /v1/voices

Returns a list of available voice presets, their associated languages, and supported output formats. Use this endpoint to validate voice IDs before synthesis requests.

  • Lists 8 voice presets
  • Includes language support per voice
  • Shows supported response formats

GET /v1/models

Returns metadata for available TTS models, including model IDs and pricing tiers. Confirms that tts-1 and tts-1-hd use the same engine with different quality levels.

  • Model IDs: tts-1, tts-1-hd
  • Pricing details
  • Engine specifications

Request Parameters

Sound wave illustration for: Request Parameters

The API accepts a single JSON body containing the text to be synthesized. You must specify the model, input text, voice, and desired audio format in every request.

Model Selection (tts-1, tts-1-hd)

Both "tts-1" and "tts-1-hd" use the same underlying engine and pricing structure. Select the model that best fits your latency requirements without impacting cost.

Input Text and Limits

Each request supports up to 4096 characters. Longer texts must be split into smaller chunks and the resulting audio files joined by your application.

Voice and Language Codes

Choose from eight available voices. While the language is often guessed from the script, explicitly setting the language code is recommended for non-English Latin text to ensure accuracy.

  • 8 preset voices available
  • Optional ISO language code
  • Latin script defaults to English

Response Formats

Sound wave illustration for: Response Formats

The API returns audio data in the response body, allowing you to save the file directly to your storage or stream it to a player. You control the format via the response_format parameter, which accepts mp3, wav, opus, flac, or pcm. Choosing the right format balances file size, compatibility, and quality for your specific use case.

All generated files contain an inaudible watermark identifying the audio as synthetic speech. This applies regardless of the format selected, ensuring consistent metadata tracking across your application’s audio assets without requiring additional processing steps.

MP3 Output

MP3 is the default format and offers a balance between file size and playback compatibility. It is suitable for web and mobile applications where bandwidth efficiency is a priority. The compression reduces storage costs while maintaining speech quality for narration and dialogue.

  • Default format for most integrations
  • Optimized for web and mobile playback
  • Smallest file size for storage efficiency

WAV and FLAC Options

WAV provides uncompressed audio, suitable for local processing or editing where data integrity is critical. FLAC offers lossless compression, reducing file size compared to WAV while preserving exact audio quality. These formats are suitable for high-fidelity requirements or archival purposes.

  • WAV: Uncompressed, maximum compatibility
  • FLAC: Lossless compression, smaller size
  • Ideal for editing and archival

PCM Raw Audio

PCM returns raw audio samples without a container. This format is useful for real-time processing pipelines or when you need precise control over audio data structure. It requires more bandwidth and storage than compressed formats and provides direct access to the audio samples.

  • Raw audio samples
  • No container overhead
  • Suitable for real-time processing

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. Successful operations return 200, while client errors return 400 or 401, and server issues return 500. Each error response includes a JSON object with a code and a human-readable message to help you debug integration issues quickly.

Common Error Codes

A 401 Unauthorized error indicates an invalid or expired API key. Ensure your Authorization header uses the format Bearer tts-... and matches the key issued in your dashboard. A 400 Bad Request typically signals malformed JSON or missing required fields like model or input.

  • 401: Invalid API key or missing Authorization header.
  • 400: Malformed request body or missing required fields.
  • 429: Too many requests; see Rate Limits below.
  • 500: Internal server error; retry after a short delay.

Rate Limit Exceeded

If you exceed 60 requests per minute, the API returns a 429 status. New accounts without top-ups are limited to 10 requests per minute. You must wait for the window to reset before sending further requests. Failed requests do not count against your character limit but do count toward the rate limit.

  • Standard limit: 60 requests per minute per key.
  • Initial limit: 10 requests per minute for new accounts.
  • Exceeding the limit returns HTTP 429.
  • Check the Retry-After header for the wait time.

Invalid Input Text

Text exceeding 4096 characters per request triggers a 400 error. Ensure your input is valid UTF-8. If the text is empty or contains only whitespace, the API returns an error. Split long texts into chunks of 4096 characters or fewer before sending them to the endpoint.

  • Maximum input length: 4096 characters per request.
  • Invalid characters may cause a 400 error.
  • Empty input results in a 400 Bad Request.
  • Spaces and punctuation count toward the character limit.
Error Handling

Rate Limits

Sound wave illustration for: Rate Limits

Rate limits are enforced per API key to ensure stable performance across the shared infrastructure. Each key allows up to 60 requests per minute once the account is funded. This limit applies to all speech synthesis attempts, regardless of text length or output format. Failed requests are free and do not count against your character limit, though they do consume a request slot within the window.

60 Requests Per Minute

Standard accounts can process 60 requests per minute. This capacity is sufficient for most batch processing workflows, provided requests are spaced appropriately. Higher volumes require queuing or key rotation strategies.

  • Limit: 60 requests/minute per key

Initial Quota Limits

New accounts without a top-up start with a reduced quota of 10 requests per minute. This lower limit applies until the first successful payment is processed. Once the account is funded, the limit increases to the standard 60 requests per minute immediately.

  • Pre-top-up: 10 requests/minute
  • Post-top-up: 60 requests/minute

Queue Behavior Under Load

Requests are processed sequentially within the quota window. If you exceed the limit, subsequent requests will wait in a queue rather than failing immediately. Processing speed is roughly real-time, meaning long texts may occupy the queue for several seconds. Under heavy load, wait times may increase.

Code Examples

Sound wave illustration for: Code Examples

Integrate the Lumivoice API using standard tools. The following examples demonstrate how to generate speech from text using cURL, Python, and JavaScript.

Ensure your API key is valid and your balance is sufficient before running these requests. Each example uses the standard endpoint structure.

cURL Command Example

Use this command to generate an audio file directly from the terminal. Replace YOUR_API_KEY with your actual key.

  • curl -X POST "https://api.playr77.com/v1/audio/speech" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello world", "voice": "nova", "response_format": "mp3"}'

Python with OpenAI SDK

Install the official OpenAI SDK and configure the base URL to point to the Lumivoice API. This method is ideal for backend services.

  • from openai import OpenAI client = OpenAI(base_url="https://api.playr77.com/v1", api_key="YOUR_API_KEY") speech_file = client.audio.speech.create( model="tts-1", voice="nova", input="Hello world" ).stream_to_file("output.mp3")

JavaScript Fetch Request

Use the native Fetch API to send a POST request. This example assumes you are building a browser-based or Node.js application.

  • fetch('https://api.playr77.com/v1/audio/speech', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'tts-1', voice: 'nova', input: 'Hello world' }) })

Testing

Sound wave illustration for: Testing

To verify your integration, begin by sending a short test phrase to the speech endpoint. This confirms that your API key is valid and that the service returns audio data correctly without consuming significant credit.

Next, retrieve the full list of available voices and models to ensure your application can dynamically select the appropriate voice. These calls return metadata such as language support and format options, helping you validate configuration settings before processing larger texts.

Sanity Check Request

Send a minimal request with 10-20 characters. Use the tts-1 model and any voice from the list. This confirms connectivity and authentication.

Voice List Retrieval

Call GET /v1/voices to fetch the 8 available presets. Verify that the returned voice IDs match your expected values and check language support.

Model Information Query

Query GET /v1/models to confirm available model IDs. This ensures your client code uses the correct model identifiers for synthesis requests.

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 API reference: create speech
  3. W3C WAI: making audio and video accessible
  4. openai-python on GitHub
  5. Node.js documentation
  6. openai-node on GitHub
  7. Tether (USDT)
  8. FFmpeg documentation
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. LibriTTS-R corpus (OpenSLR 141)
  11. curl documentation
  12. TRON developer hub: TRC-20

More on this site