Frequently asked questions
What is the API endpoint?
Send a POST request to https://api.playz77.com/v1/audio/speech. The endpoint accepts a JSON body containing your text, voice selection, and desired audio format. This single endpoint handles all speech synthesis requests for your application.
How do I authenticate requests?
Include your API key in the Authorization header using the Bearer scheme: Authorization: Bearer tts-... . You receive one active key per account, which you can find on your dashboard after signing in.
Which SDKs are supported?
We do not provide an official SDK. Instead, use the OpenAI SDKs or plain HTTP requests. The request shape matches the OpenAI speech endpoint, making integration straightforward for developers already familiar with that ecosystem.
Can I use the OpenAI Python SDK?
Yes. Configure the OpenAI Python SDK by changing the base_url to https://api.playz77.com/v1 and using your LumaSpeak API key. This allows you to use the standard client methods without modifying your code structure.
What is the maximum text length?
Each request supports up to 4096 characters of input text. For longer texts, split the content into parts of this size and join the resulting audio files. Spaces and punctuation count toward this limit.
How do I set the language?
Pass an optional ISO language code in the request body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English content.
Can I change the speech speed?
Yes, adjust the speed parameter between 0.25 and 4.0. This allows you to slow down audio for learners or speed it up for quick reviews. The default speed provides natural pacing for most educational content.
What formats can I download?
You can request audio in mp3, wav, opus, flac, or pcm formats. Choose the format that best fits your application’s needs, balancing file size and quality. All formats are generated directly from the synthesis engine.
How do I list available voices?
Send a GET request to /v1/voices. This endpoint returns details about all eight voice presets, including their names, genders, and supported languages. Use this to select a voice for your specific educational context.
What is the model ID?
Use tts-1 for standard quality or tts-1-hd for higher definition. Both models use the same engine and price. Select the model that matches your audio quality requirements for student listening materials.
Are there rate limits?
You are limited to 60 requests per minute per key. New accounts start with a limit of 10 requests per minute. This ensures fair usage while you generate audio content for your classroom or projects.
How do I handle errors?
The API returns standard HTTP status codes for errors. Failed requests are free, and any charge is returned in full if synthesis fails. Check the response body for specific error details to debug your request.
Is SSL required?
Yes, all API requests should be made over HTTPS to ensure secure transmission of your API keys and text data. The endpoint https://api.playz77.com/v1 supports standard SSL/TLS encryption for all connections.
Can I use custom headers?
You can include custom headers alongside the required Authorization header. However, only the specified fields are processed for synthesis. Ensure your custom headers do not interfere with the JSON body or standard request structure.
First request
curl
curl https://api.playz77.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.playz77.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.playz77.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 |
Getting Your API Key
LumaSpeak provides a straightforward path for educators to obtain their API key. You can sign up for an account directly on the /get-api-key/ page using either your Google account or a standard email and password combination. This process is specific to the playz77.com domain.
Sign Up on the Site
Visit the sign-up page to create your account. You may choose to authenticate via Google for immediate access or register with a traditional email and password. Note that Google sign-ups include a $0.50 trial credit, while email registrations start with zero balance.
Locate Your Key
Once registered, your dashboard displays your active API key, current balance, and usage statistics. The key follows the format tts-... and is required for all requests. You can copy this key directly from the interface to use in your development environment or curl commands.
Key Management
Each account maintains one active key at a time. If you suspect your key is compromised or need a fresh start, you can issue a new key at any time. The previous key is revoked immediately, ensuring only your current key remains valid for API access.
First Request with cURL
Send text to our TTS endpoint and receive an audio file instantly. This quickstart demonstrates a basic request using cURL, the standard command-line tool for API interactions. It covers the essential fields needed to generate speech for educational materials.
Basic POST Request
Use a POST request to https://api.playz77.com/v1/audio/speech. Include your API key in the Authorization header and set the Content-Type to application/json. The body contains the model, input text, voice, and format.
- Endpoint:
POST https://api.playz77.com/v1/audio/speech - Auth:
Authorization: Bearer YOUR_API_KEY
Required Fields
You must provide model ("tts-1" or "tts-1-hd"), input (text up to 4096 characters), voice (one of 8 presets), and response_format (mp3, wav, opus, flac, or pcm). The language field is optional; if omitted, the system guesses from the script.
model: tts-1 or tts-1-hdinput: string, max 4096 charsvoice: aria, nova, luna, sage, felix, milo, atlas, or orionresponse_format: mp3, wav, opus, flac, pcm
Response Format
On success, you receive an audio file in the requested format. Failed requests are free, with charges returned in full if synthesis fails. The response contains the binary audio data directly.
Using the OpenAI SDK
The LumaSpeak API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDK clients with minimal configuration. By simply pointing the client to our base URL, you can generate audio files directly within your educational applications or content management systems without learning a new library.
This approach simplifies integration for teachers and developers who already know the OpenAI ecosystem. You send a JSON payload with your text and voice preference, and receive the audio file ready for playback or download.
Install the SDK
Ensure you have Python 3.8+ installed. Install the official OpenAI Python library via pip, which provides the necessary HTTP client and JSON parsing tools for our API.
pip install openai
- Requires Python 3.8 or higher
Change Base URL
Configure the OpenAI client to use LumaSpeak’s API endpoint. Set the base_url to https://api.playz77.com/v1 and provide your API key in the api_key field. This redirects all requests to our servers while keeping the standard method signatures.
import os from openai import OpenAI client = OpenAI( base_url="https://api.playz77.com/v1", api_key=os.getenv("LUMASPEAK_API_KEY") )
Example Code Snippet
Generate speech using the tts-1 model. The code below sends a short text to the 'aria' voice and saves the resulting MP3 file. Adjust the voice and model parameters as needed for your specific educational content.
speech_filepath = client.audio.speech.create( model="tts-1", voice="aria", input="Welcome to our history lesson. Today we explore the ancient civilizations..." ).stream_to_file("output.mp3")
Supported Voices
LumaSpeak offers eight distinct voice presets engineered for clarity and natural rhythm, ensuring educational materials sound professional yet approachable. Each voice is derived from licensed recordings, providing a consistent baseline for audio content across your curriculum.
Female Voices
We provide four female voices tailored for different teaching styles. Aria offers a warm, clear narrator style ideal for standard reading. Nova brings a bright, upbeat energy perfect for younger students. Luna delivers a soft, storytelling tone for literature, while Sage provides a calm, instructional voice for lessons.
Male Voices
Our male voices cover a range of educational needs. Felix is energetic and great for promotional or quick updates. Milo sounds friendly and conversational for interactive exercises. Atlas serves as a neutral news reader for current events, and Orion offers a deep, documentary-style narration for history or science.
Voice Descriptions
All voices support 23 languages, including English, Spanish, French, and German. You can adjust speed between 0.25x and 4.0x to match student comprehension levels. The voices are based on licensed LibriTTS-R recordings and include an inaudible synthetic watermark.
- Aria: Warm, clear narrator
- Nova: Bright, upbeat
- Luna: Soft, storytelling
- Sage: Calm, instructional
- Felix: Energetic, promo
- Milo: Friendly, conversational
- Atlas: Neutral, news
- Orion: Deep, documentary
Audio Formats Available
LumaSpeak supports multiple audio formats to suit different educational workflows, from classroom playback to precise analysis. You can choose the right balance of quality and file size for your students’ devices.
Selecting the correct response_format in your API request determines how the audio is encoded. All formats include an inaudible watermark marking the file as synthetic speech.
MP3 and WAV
MP3 is the default choice for web players and mobile apps due to its small file size. WAV offers uncompressed, high-fidelity audio ideal for local classroom speakers or editing software.
Both formats ensure clear playback for language learning exercises and reading materials.
- MP3: Suitable for web and mobile playback
- WAV: Suitable for high-quality local playback
Opus and FLAC
Opus provides excellent compression with good quality, suitable for efficient bandwidth usage in remote learning. FLAC offers lossless compression, preserving every detail of the synthesized voice.
These formats are perfect for archiving educational content or high-precision speech analysis tools.
- Opus: Suitable for bandwidth-constrained environments
- FLAC: Lossless quality for archival and analysis
PCM Raw Audio
PCM returns raw, uncompressed 16-bit signed little-endian audio data. This format is useful for applications that handle their own encoding or need direct sample-level access.
Use PCM when your downstream system requires raw audio streams without container overhead.
- PCM: Raw 16-bit signed little-endian data

Rate Limits and Quotas
LumaSpeak’s API enforces a standard rate limit of 60 requests per minute per API key, ensuring stable performance for bulk audio generation tasks typical in educational workflows. This limit applies uniformly regardless of the model selected (tts-1 or tts-1-hd).
60 Requests Per Minute
Once your account is active, you may send up to 60 synthesis requests every minute. This capacity is sufficient for most classroom preparation needs, allowing educators to generate multiple audio files for reading materials or language exercises without significant delay.
Initial Limit
New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. This initial constraint helps manage server load during peak hours while you verify your integration setup.
Limit Increase
After completing your first top-up via USDT (TRC-20), your rate limit automatically increases to the full 60 requests per minute. This increase happens within minutes of transfer confirmation, allowing you to immediately scale your audio production for larger student cohorts.
Handling Long Texts
The API accepts input text up to 4096 characters per request, including spaces and punctuation. If your lesson plan or reading material exceeds this limit, you must split the text into smaller chunks before sending them to the endpoint.
4096 Character Limit
Each POST request to /v1/audio/speech can process a maximum of 4096 characters. This limit applies to the input field in your JSON body. Ensure your text fits within this constraint to avoid errors during synthesis.
Splitting and Joining
To handle longer texts, divide your content into segments of no more than 4096 characters. Send each segment as a separate request and receive individual audio files. You can then combine these files into a single continuous audio track for your students.
- Split text at logical boundaries like sentence ends or paragraph breaks.
- Ensure no segment exceeds 4096 characters.
- Process segments sequentially or in parallel depending on your queue load.
Audio Concatenation
After receiving multiple audio files from your requests, use your preferred audio tool to concatenate them. This creates a continuous audio file for learners.
Common Errors
Even with careful coding, API calls occasionally fail. Understanding these common errors helps you build robust integration for your educational tools without unnecessary downtime.
Invalid API Key
Ensure your key starts with tts- and is sent in the Authorization: Bearer header. Keys are unique per account; issuing a new one instantly invalidates the old one.
- Check for trailing spaces in your key string.
Rate Limit Exceeded
You are limited to 60 requests per minute. New accounts start with 10 requests per minute until the first top-up. Exceeding this triggers a 429 error.
- Implement exponential backoff for retries.
Invalid Voice ID
Use one of the 8 preset voices (e.g., aria, nova). Sending an unsupported voice name returns an error. Fetch the valid list via GET /v1/voices.
- Voice IDs are case-sensitive.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Selecting the right voice is essential for maintaining student engagement during language learning.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriVox public-domain audiobooks
- Python documentation
- LibriTTS-R paper (arXiv 2305.18802)
- Creative Commons Attribution 4.0
- Node.js documentation
- W3C WAI: making audio and video accessible
- curl documentation
- OpenAI API reference: create speech
- MDN: Web Speech API
- LibriTTS-R corpus (OpenSLR 141)
- IETF RFC 7845: Ogg Opus
