Developer Quickstart for Synthetic Speech API

By Lucky TTS Review editorial team · Updated 2026-11-18

This documentation provides the technical specifications for the Lucky TTS synthetic speech API, designed for developers integrating text-to-audio pipelines into ML datasets and speech products. You will find precise details on request shapes, supported parameters, and response handling, ensuring seamless compatibility with existing infrastructure.

The guide covers authentication, rate limits, and language controls, with concrete examples for both the OpenAI SDK and plain HTTP requests. It is tailored for engineering teams evaluating cost-per-character efficiency and data rights, offering the exact endpoints and code snippets needed to generate high-quality audio at scale.

Developer Quickstart for Synthetic Speech API

Frequently asked questions

How do I authenticate with the API?

Include your API key in the request header as Authorization: Bearer tts-.... Each account holds one active key; issuing a new key immediately invalidates the previous one. Use the key found on your /get-api-key/ dashboard page to authorize all POST and GET requests to the API endpoint.

What is the maximum character limit per request?

The input field supports up to 4096 characters per request. Spaces and punctuation count toward this limit. For texts exceeding this length, split the content into chunks of 4096 characters or fewer and join the resulting audio files manually or via a script.

Can I use the OpenAI SDK with this API?

Yes. The request shape matches the OpenAI speech endpoint. Change the SDK's base_url to https://api.playlucky101.com/v1 and provide your site-specific key. The official OpenAI SDKs work directly without modification, allowing you to use familiar code structures for generating audio files.

What audio formats are supported?

You can specify the response_format as mp3, wav, opus, flac, or pcm. These formats are available for all voice models. Select the format that best suits your storage and processing pipeline needs when constructing your JSON request body for the speech endpoint.

How do I change the voice speed?

Use the speed parameter in your request, accepting values between 0.25 and 4.0. This allows you to slow down or speed up the synthesized speech. The default speed is 1.0. Adjust this value to match the pacing required for your specific content type.

Is there a limit to requests per minute?

The rate limit is 60 requests per minute per key. Before your first top-up, this limit is reduced to 10 requests per minute. If you exceed the limit, requests may be queued or rejected. Monitor your usage dashboard to stay within these constraints.

How does the API handle long texts?

Split your text into parts of up to 4096 characters. Send each part as a separate request to the speech endpoint. Then, join the returned audio files to create a continuous audio track. This ensures you stay within the per-request character limit.

What happens if the API returns an error?

If synthesis fails, the charge is returned in full. Failed requests are free. You can retry the request after addressing any errors indicated in the response. Check your key validity and input format to ensure successful processing on subsequent attempts.

Can I specify a language explicitly?

Yes, use the optional language field with an ISO code. If omitted, the API guesses the language, defaulting to English for Latin script. Explicitly setting the language is recommended for non-English Latin-script text to ensure accurate synthesis across the 23 supported languages.

Is there a free trial for developers?

Signing in with Google provides a $0.50 trial credit, valid for 7 days, covering about 50,000 characters. Accounts created with email and password do not receive this trial credit. You can start testing immediately upon account creation and key generation.

How do I generate a new API key?

Issue a new key from your account dashboard. When a new key is generated, the old one stops working immediately. You can generate a new key at any time to rotate credentials. The new key becomes active right away for all future requests.

Do I need to install any specific SDK?

No specific SDK is required. You can use the official OpenAI SDK by adjusting the base URL, or use plain HTTP requests. There is no proprietary SDK, mobile SDK, or WordPress plugin. Any HTTP client capable of sending JSON POST requests will work.

Can I use this API with Python or Node.js?

Yes. Since the API follows the OpenAI endpoint shape, you can use the official OpenAI SDKs for Python or Node.js. Simply configure the base_url to https://api.playlucky101.com/v1 and provide your authentication key. Standard HTTP libraries also work perfectly for integration.

How do I know if a request was successful?

A successful request returns the audio file in the response body. If the synthesis fails, the API returns an error status and refunds the charge. Check the HTTP status code and response content to confirm whether the audio was generated or if an error occurred.

First request

curl

curl https://api.playlucky101.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.playlucky101.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.playlucky101.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 and Keys

Sound wave illustration for: Authentication and Keys

The API uses standard Bearer token authentication. Include your key in the Authorization header as Bearer tts-.... Use the key from your dashboard for all requests.

Each account holds one active key. Generating a new key immediately invalidates the previous one, ensuring secure rotation without downtime.

Bearer Token Usage

Bearer Token Usage

Pass your API key in the Authorization: Bearer <key> header. This works with the OpenAI SDK by setting base_url to https://api.playlucky101.com/v1.

The key grants access to speech generation and usage metrics. Keep it secure, as it identifies your billing account.

  • Format: Authorization: Bearer tts-...
  • Scope: Full account access
  • Header: Standard HTTP Bearer

Key Issuance and Rotation

Key Issuance and Rotation

Rotate keys directly from the /get-api-key/ dashboard page. Issuing a new key immediately stops the old one.

Use rotation to mitigate potential exposure without needing to update billing or voice configurations.

Single Active Key Limit

Only one key is active per account at any time. This simplifies auditing and ensures clear billing attribution.

If you lose your key, generate a new one; the old key ceases functioning instantly.

Endpoint Structure

Sound wave illustration for: Endpoint Structure

The API exposes three primary endpoints for integration. The POST endpoint handles speech synthesis, while GET endpoints retrieve available voices and model configurations. All requests target the base URL https://api.playlucky101.com/v1.

Speech Generation POST

Send text to receive an audio file. The endpoint accepts JSON bodies with parameters like model, input, voice, and response_format. Text is processed up to 4096 characters per request.

Voices List GET

Retrieve available voice presets, supported languages, and formats. This endpoint helps developers select the appropriate voice for their dataset or application without hardcoding values.

Models List GET

Fetch current model identifiers. The API currently supports tts-1 and tts-1-hd, which use the same engine and pricing structure for consistent cost-per-character calculations.

Request Body Parameters

Sound wave illustration for: Request Body Parameters

The API accepts a JSON body with specific parameters to control synthesis. Each request processes up to 4096 characters of text, ensuring consistent processing times. For longer texts, split the input into chunks and join the resulting audio files sequentially.

Model selection determines engine quality, though both models share the same price point. You can choose between "tts-1" and "tts-1-hd" depending on your quality requirements, while the voice preset defines the character's tone and style.

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

Both models use the same underlying engine and price structure. Select "tts-1" for standard generation or "tts-1-hd" for higher fidelity audio. The choice does not affect the character count billing, allowing you to optimize for quality without changing your cost model.

Input Text Limit

The API enforces a strict limit of 4096 characters per request. Spaces and punctuation count toward this total. If your dataset requires longer segments, split the text into smaller parts and concatenate the returned audio files to reconstruct the full sequence.

Voice Preset Selection

Select from eight presets based on licensed recordings from LibriTTS-R (CC BY 4.0) and LibriVox public-domain audiobook readings. Options range from warm narrators to energetic promo voices, allowing you to match the synthetic speech tone to your specific dataset needs.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Response Formats and Audio

Sound wave illustration for: Response Formats and Audio

Each API call returns a single audio file in the requested format. The response body contains the binary audio data directly, eliminating the need for additional parsing steps.

Supported Formats (MP3, WAV, Opus, FLAC, PCM)

Choose from five standard audio codecs to fit your storage and bandwidth constraints. MP3 offers high compression, while WAV and FLAC provide lossless quality. Opus and PCM are also available for specific pipeline needs.

Audio File Delivery

Audio is delivered as a binary file in the HTTP response. For long texts split into parts, you receive multiple audio files that must be concatenated sequentially to reconstruct the full speech. Requests are processed one after another, so under load a request may wait in a queue.

Synthetic Watermark

Every generated file carries an inaudible watermark that marks it as synthetic speech. This ensures clear attribution for ML datasets and speech products without affecting audio quality.

Rate Limits and Queues

Sound wave illustration for: Rate Limits and Queues

Rate limits protect the shared inference pipeline. Each API key allows up to 60 requests per minute. This limit applies uniformly regardless of model choice. Developers building large synthetic speech datasets should monitor usage to avoid throttling during bulk generation jobs.

60 Requests Per Minute

Each API key allows up to 60 requests per minute. This limit applies to all synthesis endpoints and is enforced per key. Plan your batch sizes accordingly to maintain steady throughput without exceeding the threshold.

10 Requests Before Top-Up

Accounts start with a reduced limit of 10 requests per minute before the first top-up. This lower tier applies immediately upon account creation. Upgrade your balance via USTRC-20 to unlock the full 60 requests per minute capacity.

Queue Processing Behavior

Requests are processed one after another, so under load a request may wait in a queue. Failed requests incur no charge, protecting your budget during congestion. Do not expect strict latency guarantees under heavy load.

  • Sequential processing ensures consistent resource allocation
  • No SLA guarantee for specific latency targets
  • Failed requests are free of charge
Rate Limits and Queues

Language and Speed Control

Sound wave illustration for: Language and Speed Control

Precise language control is critical for synthetic speech datasets used in ML pipelines. While the API attempts to auto-detect language, explicitly passing the ISO 639-1 code via the language parameter ensures consistent output, especially for Latin-script texts that might otherwise default to English.

ISO Language Code Input

Specify the target language using standard ISO codes. This overrides automatic detection, ensuring predictable voice behavior across your training data. Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.

Speed Range (0.25–4.0)

Adjust speech rate between 0.25 and 4.0 times normal speed. Lower speeds aid in phoneme analysis for low-resource language modeling, while higher speeds accelerate dataset generation for large-scale text-to-speech projects.

Automatic Language Guessing

If the language field is omitted, the engine guesses the language from the script. Latin script defaults to English. For non-English Latin text, always set the language parameter to avoid incorrect voice synthesis.

Error Handling and Retries

Sound wave illustration for: Error Handling and Retries

Our API ensures that failed synthesis requests incur no charge. If a request fails due to server errors or invalid parameters, the cost is returned in full, ensuring you only pay for successfully generated audio. This applies to all error conditions where audio is not delivered.

Common Error Codes

Standard HTTP status codes indicate the issue. A 401 error means your Bearer token is invalid or expired. A 429 error indicates you have exceeded the rate limit. Ensure your key is active and within rate limits before retrying.

Refund on Failure

When synthesis fails, the character count is not deducted from your balance. The system automatically credits your account for any failed attempt. You do not need to submit a manual claim; refunds are instantaneous and visible in your dashboard.

Retry Logic for Queues

Requests are processed sequentially. Under high load, your request may wait in a queue rather than failing immediately. Do not implement aggressive immediate retries, as this can exacerbate queue congestion. Wait for the standard processing time or use exponential backoff for persistent 500 errors.

SDK Integration Examples

Sound wave illustration for: SDK Integration Examples

Integrating Lucky TTS into your ML data pipeline is straightforward using standard libraries. Because the API mimics the OpenAI speech endpoint structure, you can leverage existing OpenAI SDKs by simply pointing them to our base URL.

This approach allows startups to swap in synthetic speech datasets without rewriting their ingestion logic, ensuring compatibility with existing speech product workflows.

OpenAI SDK with Base URL

Initialize the client with your API key and set the base URL to https://api.playlucky101.com/v1. Use the standard audio.speech.create method, passing your model, voice, and input text. This works identically to the OpenAI implementation, allowing seamless integration into your existing codebase.

  • Base URL: https://api.playlucky101.com/v1
  • Auth: Bearer token in headers
  • Method: audio.speech.create

Plain HTTP Requests

Send a POST request to https://api.playlucky101.com/v1/audio/speech with a JSON body containing model, input, voice, and response_format. The API returns the audio file directly in the response body, which you can save or process immediately for your dataset generation pipeline.

Curl Command Example

Use this command to test the endpoint quickly. Replace YOUR_API_KEY with your key and text with your input. This verifies connectivity before integrating into your larger data collection scripts.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Additionally, their licensing terms for synthetic data are less transparent than some alternatives.

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. LibriTTS-R paper (arXiv 2305.18802)
  4. OpenAI API reference: create speech
  5. Python documentation
  6. LibriTTS-R corpus (OpenSLR 141)
  7. ISO 639 language codes
  8. LibriVox public-domain audiobooks
  9. Tether (USDT)
  10. MDN: Web Speech API
  11. openai-node on GitHub
  12. openai-python on GitHub

More on this site