Frequently asked questions
What is the exact endpoint URL for speech generation?
Use POST https://api.play99ab.com/v1/audio/speech. Send a JSON body with model, input, voice, response_format, and optional speed and language parameters. This endpoint accepts standard TTS requests and returns the generated audio file directly in the response body.
Does the API support streaming audio response?
No. The API returns the complete audio file after synthesis finishes. There is no WebSocket or real-time partial audio streaming. Requests are processed sequentially, so longer texts may experience queue delays before the final file is returned.
How do I specify the language in the request?
Pass the ISO code in the language field. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language is recommended for non-English Latin-script text to ensure accuracy.
Can I use the official OpenAI Python SDK?
Yes. The request shape matches the OpenAI speech endpoint. Change the SDK's base_url to https://api.play99ab.com/v1 and use your site’s key. This allows you to use existing OpenAI SDK code with minimal configuration changes.
What happens if I send text longer than 4096 characters?
Split your text into parts of up to 4096 characters. Send each part as a separate request, then join the resulting audio files. This ensures each request stays within the character limit and processes correctly.
Are there headers required for the request?
Yes. Include Authorization: Bearer tts-... with your API key in the request headers. This authenticates your request. Ensure the key is active and has sufficient balance, as failed requests are free but valid ones incur charges.
How do I handle rate limit errors in code?
The limit is 60 requests per minute per key. Implement retry logic with exponential backoff when you receive a rate limit error. Monitor your usage via the dashboard.
Is SSML supported in the input text?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. Input is plain text. Use the speed parameter to adjust pacing if you need to control the delivery rate of the speech.
What is the default response format?
The default format is mp3. You can specify other formats like wav, opus, flac, or pcm in the response_format field. If not specified, the API returns the audio file in mp3 format by default.
Can I change my API key after creation?
Yes. You can issue a new key at any time from your dashboard. The old key stops working immediately when the new one is issued. This allows you to rotate keys securely without downtime.
Do I need to install a specific SDK?
No. You can use the official OpenAI SDK or plain HTTP requests. There is no dedicated VerbaLingua SDK. Use standard HTTP libraries or the OpenAI SDK with the adjusted base URL for integration.
How do I detect errors in the JSON response?
Check the HTTP status code. Failed requests return a non-200 status code with a JSON error body. Successful requests return 200 with the audio file. Inspect the response headers and body for status details.
Is the API synchronous or asynchronous?
The API is synchronous. Requests are processed one after another. You receive the audio file only after synthesis completes. Under load, requests may wait in a queue before processing begins.
Can I request multiple voices in one call?
No. Each request supports only one voice preset. To use multiple voices, send separate requests for each voice and join the resulting audio files. The voice field accepts a single voice ID per request.
First request
curl
curl https://api.play99ab.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.play99ab.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.play99ab.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
Authentication is handled via a Bearer token sent in the Authorization header of every request. This single key identifies your account and tracks usage against your balance.
Bearer token format
Include your key exactly as Authorization: Bearer tts-your_key_here. The prefix tts- is required. Any deviation results in an authentication failure.
Key management
Each account holds one active key. You can view your current key and usage stats on the /get-api-key/ dashboard.
Issuing new keys
Generate a new key at any time via the dashboard. The old key stops working immediately, ensuring no overlap or confusion between sessions.
Endpoints overview
The API exposes three primary endpoints for generating audio and managing resources. The speech endpoint accepts text and configuration parameters to return synthesized audio files, while the voices and models endpoints provide metadata about available options.
All endpoints require Bearer token authentication in the request header. Responses are returned in standard JSON formats, ensuring compatibility with existing HTTP clients and SDKs without requiring custom parsers.
Speech generation endpoint
Use POST to https://api.play99ab.com/v1/audio/speech. Submit a JSON body with model, input text, voice preset, and response format. The endpoint processes requests sequentially, returning the generated audio file upon completion.
Failed requests do not incur charges. The endpoint supports text up to 4096 characters per request. For longer texts, split the input and join the resulting audio files manually.
- Endpoint: POST /v1/audio/speech
- Auth: Bearer token required
- Input: JSON body with text and parameters
- Output: Audio file or error JSON
Voices listing endpoint
Call GET https://api.play99ab.com/v1/voices to retrieve the list of 8 available voice presets, their associated languages, and supported audio formats. This endpoint helps you select the appropriate voice for your multilingual application.
Each voice preset is designed for specific use cases, from warm narration to energetic promos. The response includes metadata for each voice, enabling dynamic UI updates based on available options.
- Endpoint: GET /v1/voices
- Returns: Voice presets, languages, formats
- Use: Select voice for synthesis
- Updates: Real-time availability
Models endpoint
Access GET https://api.play99ab.com/v1/models to view the available TTS models, including tts-1 and tts-1-hd. Both models use the same engine and pricing, offering flexibility in selection without cost differences.
The models endpoint provides essential information for configuring requests. It ensures compatibility with the OpenAI SDK by exposing standard model identifiers, allowing seamless integration into existing workflows.
- Endpoint: GET /v1/models
- Returns: Available TTS models
- Models: tts-1, tts-1-hd
- Pricing: Identical for both models
Request parameters
Configure the core parameters to generate speech. The API accepts standard fields compatible with the OpenAI speech endpoint, ensuring easy integration for product teams using existing client libraries.
You define the output characteristics by selecting a model, providing input text, and choosing a voice preset. Each parameter directly influences the audio generation process and billing.
Model selection ['Choose between tts-1 for standard quality or tts-1-hd for higher fidelity. Both models use the same underlying engine and are priced identically at $10 per million characters.', 'Selecting tts-1-hd does not incur extra costs but may slightly increase processing time for longer texts.'] ['tts-1: Standard quality, consistent performance', 'tts-1-hd: Higher fidelity, same price']
Input text limits ['The input field accepts plain text up to 4,096 characters per request. Spaces and punctuation count toward this limit. For longer content, split your text into chunks and concatenate the resulting audio files.', 'Requests are processed sequentially; under load, longer texts may experience queue delays.'] ['Max 4,096 characters per request', 'Spaces and punctuation count as characters']
Voice preset selection ['The voice parameter accepts one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice is trained on licensed recordings and supports all 23 available languages.', 'Specify the language ISO code if auto-detection fails, especially for non-English Latin script texts.'] ['8 voice presets available', 'All voices support 23 languages']
Response formats
The API returns binary audio data directly in the response body, eliminating the need for separate download steps. The output format is determined by the response_format field in your request payload, allowing you to choose the best balance between file size and compatibility for your specific application environment.
MP3 audio data
MP3 is the default and most universally supported format. It provides a good balance between audio quality and file size, making it ideal for web applications and mobile apps where bandwidth efficiency matters. The generated MP3 files are fully playable in standard media players and browsers.
WAV audio data
WAV offers uncompressed audio, preserving the full fidelity of the synthesis engine. This format is best for applications requiring high-quality audio processing or when you need to perform further audio editing on the generated clips. Note that WAV files are significantly larger than MP3s.
Opus and FLAC support
Opus provides excellent compression for efficient delivery, while FLAC offers lossless compression for archival quality. Choose Opus for efficient delivery, or FLAC if you need lossless audio.
OpenAI SDK integration
Since the API mirrors the OpenAI speech endpoint structure, you can leverage existing OpenAI SDKs with minimal configuration changes. This compatibility allows product teams to switch providers without rewriting their core synthesis logic or learning a new client library.
Base URL configuration
Set the base_url to https://api.play99ab.com/v1 in your SDK client instance. This directs all requests to the VerbaLingua infrastructure while maintaining the standard request shape.
Client initialization
Initialize the client using your unique Bearer token. Ensure the token starts with tts- and is passed in the Authorization header. The SDK handles the header injection automatically when configured correctly.
Method compatibility
Use the standard Audio or Speech creation methods provided by the official OpenAI SDK. The JSON body fields model, input, voice, and response_format are fully compatible, allowing you to generate audio files directly.

Error handling
The API returns specific HTTP status codes to help you handle failures gracefully. Most errors include a JSON body with an error message, allowing your application to log details or adjust behavior without crashing.
Rate limit errors
If you exceed 60 requests per minute, the API returns a 429 status code. This limit resets every minute, so implement exponential backoff or queue your requests to avoid wasting characters on failed attempts.
Invalid request bodies
A 400 status indicates a malformed request, such as exceeding the 4096 character limit or providing an unsupported response format. Check your input payload structure and ensure all required fields are present and valid.
Authentication failures
Return 401 if the Bearer token is missing or malformed. Ensure your Authorization header follows the Bearer <key> format exactly. If your key is invalid, regenerate it via the dashboard.
Rate limits and concurrency
The API enforces a strict limit of 60 requests per minute per active key. For new accounts without a top-up, this limit is reduced to 10 requests per minute. This constraint applies to all speech generation endpoints and ensures stable performance during high-volume usage.
60 requests per minute
Each API key is allowed 60 requests per minute. New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. This limit resets every 60 seconds and is calculated per key, not per IP address.
Queue behavior under load
Requests are processed sequentially. If the limit is reached, subsequent requests wait in a queue. Short phrases may take a few seconds to generate, while longer texts process at roughly real-time speed (25 characters per second). Under heavy load, wait times increase as requests wait for their turn.
Retry strategies
Implement exponential backoff for failed requests. If you receive a 429 Too Many Requests error, wait before retrying. Failed synthesis requests are free, so retrying does not incur additional costs if the initial attempt fails. Always handle rate limit headers in your integration logic.
Language specification
VerbaLingua supports 23 languages, from Arabic to Turkish. While the API can guess language from script, explicit control ensures consistency in multilingual apps. Use the language parameter with standard ISO codes to lock the output language, preventing unwanted auto-detection shifts.
Accurate language specification is critical for language learning products where phonetic precision matters. Explicit codes avoid ambiguity, especially when mixing scripts or using Latin text for non-English languages.
ISO code usage
Pass the language field in your JSON body with the ISO 639-1 code (e.g., "de" for German, "ja" for Japanese). This applies to all 23 supported languages. If omitted, the API attempts to infer the language from the input text’s script.
Explicit codes override inference. For mixed-language content, you must split requests or choose the dominant language. The GET /v1/voices endpoint lists all supported languages and their codes.
- Supported codes include:
ar,zh,da,nl,en,fi,fr,de,el,he,hi,it,ja,ko,ms,no,pl,pt,ru,es,sw,sv,tr. - Voices are language-agnostic; any preset voice can speak any supported language when the code is set.
Auto-detection fallback
If language is unset, the system guesses based on Unicode scripts. Latin script defaults to English unless other cues are present. Cyrillic defaults to Russian.
This fallback works for single-language texts. For code-switching or ambiguous input, detection may fail, resulting in an English voice reading foreign text with an accent. Always set language for non-English Latin text to ensure correct pronunciation.
- Detection relies on script patterns, not semantic analysis.
- Incorrect guessing leads to unnatural prosody; explicit codes are recommended for production apps.
Non-Latin script handling
The API handles CJK, Cyrillic, Arabic, Hebrew, and Devanageti scripts natively. Ensure your input text uses standard Unicode characters. Combining marks or unusual encodings may cause detection errors or synthesis failures.
For languages like Hindi or Greek, explicit ISO codes prevent misidentification. The system does not support Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, or Bengali; requests for these will fail.
- Ensure text is UTF-8 encoded.
- Verify supported languages list before integrating new locales.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Users need intuitive, adaptive lessons that fit seamlessly into their daily routines for effective language acquisition.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- Creative Commons Attribution 4.0
- curl documentation
- LibriVox public-domain audiobooks
- OpenAI API reference: create speech
- TRON developer hub: TRC-20
- Python documentation
- LibriTTS-R paper (arXiv 2305.18802)
- Node.js documentation
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- MDN: Web Speech API
