Text-to-Speech API: Quickstart Guide for Developers

By LumaSpeak editorial team · Updated 2026-11-18

This documentation provides a practical guide for developers integrating LumaSpeak’s text-to-speech API into educational applications. Whether you are building language learning tools, creating accessible reading materials, or automating audio content for students, you will find clear examples for every step. We focus on the technical details you need to generate high-quality speech without unnecessary complexity, ensuring your projects run smoothly in classroom or remote learning environments.

The guide covers everything from obtaining your API key to handling long texts and managing rate limits. You will learn how to use standard tools like cURL and the OpenAI SDK, explore our eight voice presets, and understand supported audio formats. All information is based on current facts, so you can implement reliable audio generation for schools and teachers with confidence and precision.

Text-to-Speech API: Quickstart Guide for Developers

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

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

Getting Your API Key

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

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

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

Sound wave illustration for: 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-hd
  • input: string, max 4096 chars
  • voice: aria, nova, luna, sage, felix, milo, atlas, or orion
  • response_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

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

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

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

Rate Limits and Quotas

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

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

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

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. LibriVox public-domain audiobooks
  3. Python documentation
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. Creative Commons Attribution 4.0
  6. Node.js documentation
  7. W3C WAI: making audio and video accessible
  8. curl documentation
  9. OpenAI API reference: create speech
  10. MDN: Web Speech API
  11. LibriTTS-R corpus (OpenSLR 141)
  12. IETF RFC 7845: Ogg Opus

More on this site