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.mp3Python (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 | |
|---|---|
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 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
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
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
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
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
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
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

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
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
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.
23 languages
Any voice speaks any of these languages.
