Frequently asked questions
How do I get an API key?
Navigate to /get-api-key/ and sign in with Google or create an account with email and password. Your unique API key appears on the dashboard immediately. Each account holds one active key; issuing a new one invalidates the previous one instantly.
What is the base URL?
The API base URL is https://api.playnn77.com/v1. You send POST requests to https://api.playnn77.com/v1/audio/speech for audio generation and GET requests to /v1/voices or /v1/models to retrieve available options and pricing details.
How do I use the OpenAI SDK?
Use the official OpenAI SDKs by changing the base_url to https://api.playnn77.com/v1. Authenticate using your Bearer token. The request shape matches the OpenAI speech endpoint, allowing you to use standard libraries without custom integration code.
What models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure. Select either model in your request body to generate audio files. The choice does not affect cost, only the specific synthesis parameters.
How do I set the language?
Include the optional language field with an ISO code in your request. If omitted, the system guesses the language based on the script, defaulting to English for Latin text. Explicitly set the language for non-English Latin-script text to ensure accuracy.
What is the speed range?
You can adjust the speech speed between 0.25 and 4.0. Set the speed parameter in your request to control the playback rate. This allows you to slow down complex educational content or speed up simple announcements for efficiency.
Can I use MP3 output?
Yes, MP3 is a supported response format. You can also choose WAV, OPUS, FLAC, or PCM. Specify your preferred format in the response_format field of your POST request to receive the audio file in the desired codec.
How do I handle errors?
Failed requests are free: if synthesis fails, the charge is returned in full. If synthesis fails, you receive an error response without any cost. Check your request parameters, such as character limits and valid voice names, to resolve common issues.
What happens if I exceed rate limits?
The limit is 60 requests per minute per key, or 10 per minute before your first top-up. Requests are processed sequentially, so exceeding limits may cause your request to wait in a queue until capacity becomes available.
Is the API synchronous?
Yes, the API is synchronous. You send a text request and receive the audio file in the response. For longer texts, split the input into parts of up to 4096 characters, generate each part, and join the resulting audio files.
Do I need to install a package?
No specific package is required. You can use the official OpenAI SDK by pointing it to our base URL, or make standard HTTP POST requests. Any tool capable of sending JSON bodies and handling Bearer token authentication will work.
How do I rotate my key?
Generate a new API key from your dashboard at any time. The new key becomes active immediately, and the previous key stops working at once. This allows you to secure your account without interrupting your current integrations.
What is the input text limit?
Each request accepts up to 4096 characters. Spaces and punctuation count toward this limit. For longer texts, split the content into chunks of 4096 characters or less, generate audio for each chunk, and concatenate the resulting audio files.
How are voices selected?
Choose from eight presets: aria, nova, luna, sage, felix, milo, atlas, orion. Each voice has a distinct tone, from warm narration to deep documentary styles. Any voice can speak any of the 23 supported languages.
First request
curl
curl https://api.playnn77.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.playnn77.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.playnn77.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
Access the Lectura TTS API using a unique API key generated in your dashboard. Each account holds one active key at a time, which serves as the sole credential for all requests. Keys are issued upon sign-up or top-up and appear on your dashboard alongside your balance and usage statistics.
API Key Format
Keys follow the format tts- followed by a unique alphanumeric string (e.g., tts-abc123). This key identifies your account and deducts credits from your balance. Ensure you copy the key exactly as displayed, as extra spaces can cause authentication failures.
Bearer Token
Include your key in the HTTP Authorization header as a Bearer token. The header must read Authorization: Bearer tts-<your-key>. This standard format works with the official OpenAI SDKs by simply updating the base_url to https://api.playnn77.com/v1.
Key Rotation
If you suspect a key has been compromised or wish to refresh credentials, you can issue a new key from the dashboard at any time. The old key becomes invalid immediately upon the creation of the new one, ensuring no overlap in active credentials.
Endpoints
Lectura provides a straightforward REST API for text-to-speech conversion. The primary endpoint handles audio generation, while secondary endpoints allow you to query available voices and model configurations. All endpoints use standard JSON formats compatible with common SDKs.
Speech Generation
Send a POST request to https://api.playnn77.com/v1/audio/speech with your text, selected voice, and desired audio format. The API returns the synthesized audio file directly in the response body.
- Endpoint: POST /v1/audio/speech
- Input: JSON body with
model,input,voice, andresponse_format
List Voices
Retrieve the full list of available voices, supported languages, and output formats by sending a GET request to /v1/voices. This helps you verify which presets are available for your specific use case.
- Endpoint: GET /v1/voices
- Returns voice IDs, languages, formats, and price
List Models
Query available models via GET /v1/models. Currently, the API supports tts-1 and tts-1-hd, which share the same engine and pricing structure. Use this endpoint to confirm model availability.
- Endpoint: GET /v1/models
- Returns
tts-1andtts-1-hdoptions
Request Parameters
Lectura’s API accepts plain text input for speech synthesis, with a strict limit of 4,096 characters per request. Spaces and punctuation are counted toward this limit. For texts exceeding this length, split the input into smaller chunks and join the resulting audio files.
Input Text
Send the text via the input field in the JSON body. The system supports 23 languages, including English, Spanish, and Chinese. If the language field is omitted, the API guesses the language from the script, defaulting to English for Latin characters.
- Maximum length: 4,096 characters per request.
- Characters include spaces and punctuation.
- Supported languages: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
Voice Selection
Choose from eight preset voices using the voice parameter. Each voice has a distinct tone, suitable for different educational contexts. All voices can speak any of the supported languages.
- Female voices: aria (warm narrator), nova (bright), luna (soft storytelling), sage (calm instruction).
- Male voices: felix (energetic promo), milo (friendly), atlas (neutral news), orion (deep documentary).
Speed Control
Adjust the playback speed using the speed field, allowing values between 0.25 and 4.0. The default speed is 1.0. This feature helps tailor the audio for listening exercises or quick announcements.
- Range: 0.25 to 4.0.
- Default: 1.0.
Response Formats
The API returns the generated audio directly in the response body, allowing immediate playback or file saving. Supported formats include mp3, wav, opus, flac, and pcm. Headers provide context for file handling.
No additional JSON payload is included with successful audio responses, keeping the data stream efficient for high-volume school announcements. Errors return specific codes to help identify issues quickly without external documentation.
Audio File Return
The primary response contains the raw audio bytes. Select your preferred format via the response_format parameter. The file is ready for direct use in audio players or storage systems.
- Supported formats: mp3, wav, opus, flac, pcm
JSON Metadata
Standard HTTP headers indicate content type and length. No additional JSON payload is included with successful audio responses, keeping the data stream efficient for high-volume school announcements.
Error Codes
- 400 Bad Request: Invalid parameters or malformed JSON
- 401 Unauthorized: Missing or invalid API key
- 429 Too Many Requests: Rate limit exceeded (60 req/min)
Rate Limits
Your API key allows 60 requests per minute. If you exceed this limit, the API returns a 429 error. This limit applies per key, so generating multiple audio files simultaneously requires careful request management.
60 Requests Per Minute
Each request consumes one unit of your 60 RPM quota. For batch processing, ensure your application waits for a response before sending the next request. This prevents accidental throttling during high-volume lesson audio generation.
10 Requests Before Top-Up
New accounts without a USDT top-up are limited to 10 requests per minute. This lower limit ensures fair usage during the free trial period. Once you top up with USDT (TRC-20), the limit increases to the standard 60 requests per minute.
Queued Processing
Requests are processed sequentially. Under load, your request may wait in a queue before synthesis begins. This ensures consistent audio quality but may increase total generation time for long texts. Monitor your application's response time to adjust batch sizes accordingly.

Code Examples
Send text to the speech endpoint and receive an audio file. The API accepts standard JSON bodies, allowing you to choose the model, voice, and output format.
Below are three common ways to integrate the API into your workflow, whether you are testing via command line or building a classroom audio tool.
cURL Command
Use this command to generate speech directly from your terminal. Replace the placeholder with your API key and desired text.
- curl -X POST "https://api.playnn77.com/v1/audio/speech" \ -H "Authorization: Bearer tts-your-key-here" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Hello class, today we learn history.", "voice": "aria", "response_format": "mp3"}'
Python SDK
Install the official OpenAI SDK and point it to our base URL. This allows you to use familiar Python methods to generate audio files for lesson plans.
- import openai client = openai.OpenAI(base_url="https://api.playnn77.com/v1", api_key="tts-your-key-here") with client.audio.speech.create( model="tts-1", voice="nova", input="Science class is starting." ) as response: response.stream_to_file("lesson.mp3")
JavaScript Fetch
Use the native fetch API to send requests from a browser or Node.js environment. This approach works well for simple web-based reading tools.
- fetch("https://api.playnn77.com/v1/audio/speech", { method: "POST", headers: { "Authorization": "Bearer tts-your-key-here", "Content-Type": "application/json" }, body: JSON.stringify({ model: "tts-1", voice: "sage", input: "Announcement: Library is closed." }) })
Error Handling
Errors follow standard HTTP conventions. The API returns specific codes to help you fix request issues quickly without unnecessary debugging.
400 Bad Request
This error occurs when the input is invalid. Common causes include exceeding the 4096 character limit per request, using an unsupported format, or providing an incorrect voice ID.
- Check text length and encoding.
- Verify voice names against the /v1/voices endpoint.
401 Unauthorized
The API key is missing or invalid. Ensure your Authorization header uses the Bearer token format. If you rotated your key, the old one stops immediately.
- Verify the 'tts-...' prefix.
- Check for trailing spaces in the key.
429 Too Many Requests
You have exceeded the rate limit of 60 requests per minute. New accounts start with a limit of 10 requests per minute. The API returns this code until the window resets.
- Implement exponential backoff.
- Top up to increase limits.
Long Text Handling
For texts exceeding 4096 characters, the API requires manual splitting. Each request must contain a segment of 4096 characters or fewer. Spaces and punctuation count toward this limit, so precise chunking is necessary to avoid truncation.
4096 Character Limit
The input field strictly caps at 4096 characters per request. Any text beyond this threshold must be divided into multiple requests. This constraint applies to all models and voices.
Splitting Logic
Split your lesson text into chunks not exceeding 4096 characters. Process these chunks sequentially or in parallel, depending on your rate limit capacity. Ensure no character is lost or duplicated during the split.
- Count spaces and punctuation as characters.
- Maintain logical sentence breaks where possible.
- Keep each chunk ≤ 4096 characters.
Audio Joining
After generating audio for each chunk, concatenate the resulting files into a single audio file. This ensures a continuous listening experience for students. The API returns individual audio files per request, which your client code must merge.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Teachers can easily design engaging lessons without needing technical skills to manage their classrooms efficiently.
23 languages
Any voice speaks any of these languages.
