Frequently asked questions
How do I authenticate requests?
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. Ensure the key is passed with every request to the https://api.play79y.com/v1 endpoint for proper authentication and billing tracking.
What is the maximum input length?
The API accepts up to 4096 characters per request. For longer texts, split the input into chunks of this size and join the resulting audio files. Spaces and punctuation count toward the character limit, which directly affects your billing calculation based on the total character count.
Can I use the OpenAI Python SDK?
Yes. The endpoint shape matches the OpenAI speech endpoint. Use the official OpenAI SDK by setting the base_url to https://api.play79y.com/v1 and providing your LinguaFlow API key. This allows you to use existing OpenAI client code with minimal configuration changes for integration.
How do I change the base URL?
Update your SDK configuration or HTTP client to point to https://api.play79y.com/v1. This base URL handles all endpoints, including speech synthesis and voice listing. Ensure your authentication header uses the tts- prefix key associated with your specific LinguaFlow account for successful request processing.
What are the rate limits?
The limit is 60 requests per minute per key. New accounts start with a lower limit of 10 requests per minute until the first top-up is completed. These limits apply to requests; failed requests are free, but still count toward the rate limit.
What happens if I exceed the rate limit?
Requests are processed sequentially, so exceeding limits may cause queuing delays. If the limit is strictly enforced, requests may be rejected. Failed requests are free, but successful ones are charged. Monitor your rate limit headers to adjust your request frequency and ensure smooth audio generation workflows.
How do I get a list of voices?
Send a GET request to /v1/voices to retrieve available voices, languages, formats, and pricing. This endpoint provides the eight preset voices and their supported languages. Use this data to select the appropriate voice parameter for your synthesis requests, ensuring compatibility with your target language and format.
Are there any hidden API fees?
No. Pricing is strictly $0.01 per 1,000 characters. Failed requests are free. There are no monthly plans, seats, or minimum spend requirements. Billing is based solely on characters processed, including spaces and punctuation. Top-ups via USDT (TRC-20) are credited automatically.
First request
curl
curl https://api.play79y.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.play79y.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.play79y.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
LinguaFlow uses standard Bearer token authorization for API access. Include your unique API key in the Authorization header of every request. This key identifies your account and tracks usage against your balance.
Bearer token authorization
Send your key as Authorization: Bearer tts-... in the HTTP header. The API validates this token before processing synthesis requests. Ensure the key is transmitted securely over HTTPS.
One active key per account
Each account maintains a single active API key. There are no separate keys for different environments or users within the same account. All requests using this key count toward your shared rate limits and usage quota.
Immediate key rotation support
You can issue a new API key at any time via the dashboard. The previous key stops working immediately upon generation of the new one. This allows instant rotation without downtime if a key is compromised.
Main Endpoint
The core synthesis endpoint accepts text and returns generated audio files. This endpoint handles the conversion of your input string into audible speech, supporting multiple audio formats and voice configurations. It is designed to be straightforward for integration with existing edtech workflows.
You send a POST request with your API key and the text to be converted. The service processes the request and returns the audio binary, allowing you to play, store, or embed the result directly in your language learning application.
POST /v1/audio/speech
Send your synthesis requests to this endpoint. It requires a valid Bearer token in the Authorization header. The base URL is https://api.play79y.com/v1.
Ensure your text input does not exceed 4096 characters per request. For longer texts, split the input into chunks and join the resulting audio files.
- Endpoint: https://api.play79y.com/v1/audio/speech
- Method: POST
- Content-Type: application/json
JSON body request format
The request body must contain the model, input, and voice fields. You can optionally specify response_format, speed, and language.
The model field accepts "tts-1" or "tts-1-hd", which use the same engine and price. The input field holds the text to convert. The voice field selects one of the eight presets.
- model: "tts-1" or "tts-1-hd"
- input: string (max 4096 chars)
- voice: e.g., "aria", "nova"
Audio file response
On success, the endpoint returns the audio file in the requested format. The response body contains the binary audio data.
The HTTP response will include the appropriate Content-Type header for the format, such as audio/mpeg for MP3 or audio/wav for WAV.
Request Parameters
Configure the synthesis engine and input payload for each request. Select the model, define the text, and choose a voice preset to generate audio.
Model: tts-1 or tts-1-hd
Both models use the same engine and price. Choose tts-1 for standard generation or tts-1-hd for higher fidelity. Both support the same voice presets and response formats.
Input: text up to 4096 chars
Pass your text in the input field. The API accepts up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer texts, split the input into chunks and join the resulting audio files.
Voice: one of 8 presets
Select a voice from the eight available presets. Voices include female options like Aria and Nova, and male options like Felix and Atlas. Each voice can speak any of the 23 supported languages.
- 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
Response Formats
The API returns synthesized audio as binary data in the requested format. Supported output formats include MP3, WAV, OPUS, FLAC, and PCM. This flexibility allows integration with various edtech players and accessibility tools without additional conversion steps.
MP3, WAV, OPUS, FLAC, PCM
Select your preferred format via the response_format parameter. MP3 and OPUS are efficient compressed formats, while WAV and FLAC offer lossless quality for archival. PCM provides raw uncompressed audio for precise waveform processing.
- MP3: Standard compressed audio
- WAV: Uncompressed PCM audio
- OPUS: Efficient low-latency codec
- FLAC: Lossless compression
- PCM: Raw uncompressed audio
Binary audio data return
The response body contains the raw audio bytes. No JSON wrapper surrounds the audio data. Directly write the response body to a file or stream it to your media player.
Content-type headers
The Content-Type header matches the requested format (e.g., audio/mpeg, audio/wav). Use this header to correctly parse the response in your client application.
Rate Limits
LinguaFlow enforces a rate limit of 60 requests per minute per API key. This capacity is sufficient for most language learning applications, including pronunciation drills and reading comprehension features, without requiring complex infrastructure.
60 requests per minute
After your account is active, you can make up to 60 requests per minute. This allows for steady generation of audio files for educational content.
10 requests before first top-up
New accounts start with a lower limit of 10 requests per minute. This applies until you complete your first top-up. Use this period to test integration with the $0.50 free trial credit.
Per key limitation
The rate limit applies to each API key individually. You can issue a new key at any time, which immediately stops the old key. This allows you to issue a new key, but note that the rate limit applies per key, and the old key stops working immediately.

OpenAI SDK Integration
LinguaFlow is fully compatible with the official OpenAI SDKs. By adjusting the base_url to https://api.play79y.com/v1, developers can route standard TTS requests through existing client libraries without rewriting core logic.
This approach allows teams to maintain familiar code structures while leveraging our specific voice presets and pricing model. It eliminates the need for custom HTTP wrappers or proprietary client implementations.
Change base_url endpoint
Update your SDK configuration to point to https://api.play79y.com/v1. This ensures all POST requests for audio synthesis are directed to LinguaFlow’s API gateway instead of OpenAI’s infrastructure.
Use official OpenAI SDKs
You can use any official OpenAI SDK (Python, Node.js, etc.). Simply pass your LinguaFlow API key in the Authorization header. The SDK handles serialization and retries exactly as it would for OpenAI endpoints.
Standard request structure
Send a JSON body with model, input, voice, and response_format. The request shape matches the OpenAI speech endpoint exactly. Ensure your key starts with tts- for proper authentication.
Error Handling
When synthesis fails, your account is not charged. The system returns the full credit for that request, ensuring you only pay for successfully generated audio files. This applies to any error that prevents audio creation, protecting your balance from wasted requests.
You can rely on standard HTTP status codes to identify issues. The API returns clear error responses when parameters are invalid or limits are exceeded, allowing your application to handle failures gracefully without manual billing adjustments.
Failed requests are free
If the synthesis engine cannot produce audio from your input, the request is marked as failed and no characters are deducted from your balance. This ensures that temporary processing errors or invalid inputs do not result in financial loss.
You can safely retry failed requests. Since the character count is not consumed, retrying a failed request with corrected parameters will not incur additional charges, making it cost-effective to handle transient issues.
- No charge for failed synthesis attempts
- Automatic credit return to your balance
- Safe to retry with corrected inputs
Charge returned on failure
The billing system automatically detects failed requests and refunds the corresponding amount. This process is immediate, so your available balance reflects the correction right away. You do not need to submit a support ticket for failed requests.
This feature is particularly useful for high-volume applications where intermittent network issues or input errors might occur. You can monitor your usage dashboard to see the number of successful versus failed requests.
- Automatic refund for failed requests
- Immediate balance update
- No manual refund process required
Standard HTTP error codes
The API uses standard HTTP status codes to indicate the status of your request. Common codes include 400 for bad requests, 401 for unauthorized access, and 429 for rate limit exceeded.
These codes help you debug integration issues quickly. For example, a 429 error indicates you have exceeded the 60 requests per minute limit, prompting you to implement a retry mechanism with exponential backoff.
- 400: Bad Request (invalid parameters)
- 401: Unauthorized (invalid or missing API key)
- 429: Too Many Requests (rate limit exceeded)
- 500: Internal Server Error (transient issue)
Voices Endpoint
The /v1/voices endpoint provides a complete list of available synthetic voices, their supported languages, and associated formats. This allows your application to dynamically populate voice selection menus based on real-time inventory and pricing data.
You can filter results by specific language codes or voice names to ensure compatibility with your language learning content. The response includes metadata necessary for configuring the POST /v1/audio/speech request accurately.
GET /v1/voices
Send a GET request to retrieve the full catalog of eight voice presets. The response returns a JSON object containing details for each voice, including unique identifiers, gender, style description, supported output formats, and pricing.
This endpoint is essential for building user interfaces that allow learners to preview or select voices for pronunciation drills and reading comprehension exercises without hardcoding voice IDs.
- Returns a JSON array of voice objects
- Includes voice ID, name, gender, and description
- Lists supported
response_formatoptions per voice - Indicates available
languagecodes for each voice
List available voices
The API returns eight distinct presets: aria, nova, luna, and sage (female); felix, milo, atlas, and orion (male). Each voice is designed for specific use cases, from warm narration to energetic promotional content.
You can map these voices to educational contexts, such as using atlas for neutral news reading or luna for soft storytelling, ensuring the synthetic speech matches the pedagogical intent.
Check language support
All eight voices support 23 languages, including Arabic, Chinese, English, French, German, Japanese, Spanish, and others. Any voice can speak any supported language, allowing you to switch voices while maintaining language consistency.
Use this endpoint to verify which languages are available before attempting synthesis. If a language is not supported, the API may return an error or guess the language based on the script, so setting the language explicitly is recommended.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Mastering language learning requires consistent engagement and adaptive strategies for product teams.
23 languages
Any voice speaks any of these languages.
