Frequently asked questions
What is the OpenAI SDK base URL?
Use https://api.ba11.info/v1 as the base URL. This allows official OpenAI SDKs to work by changing the base URL and using your site-specific key. The request shape matches the OpenAI speech endpoint exactly, ensuring seamless integration for existing OpenAI clients without requiring custom client code.
How do I authenticate with the API?
Send an Authorization header with the value Bearer followed by your API key (e.g., Bearer tts-...). Each account has one active key. You can issue a new key at any time, which immediately invalidates the previous one. Ensure your key is included in every request to the API endpoint.
Which is better: OpenAI SDK or Curl?
Both are equally valid. The OpenAI SDK works by setting the base URL to https://api.ba11.info/v1. Curl is useful for quick testing. The API accepts standard JSON bodies for both. Choose based on your team's existing infrastructure and preference for programmatic SDK integration versus manual request construction.
What is the maximum input character limit?
The maximum input is 4096 characters per request. If your text exceeds this limit, you must split it into parts of up to 4096 characters. Generate audio for each part separately and then join the resulting audio files to create the final output for the complete text.
How do I specify the language in the request?
Include the optional language field with an ISO code. If omitted, the system guesses the language from the script, defaulting to English for Latin text. For non-English Latin-script text, always set the language explicitly. Supported languages include Arabic, Chinese, English, French, German, Spanish, and others listed in the API.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key. Requests are processed sequentially, so exceeding this may cause your request to wait in a queue. Before the first top-up, the limit is 10 requests per minute. Failed requests are free: if synthesis fails, the charge is returned in full.
Are there limits on audio file size?
The API does not impose a maximum file size constraint. The limit is on input text characters (4096). Audio generation time is roughly real-time, approximately 25 characters per second. Larger texts require splitting and joining audio files, but the API does not impose a maximum file size constraint.
Can I use the same key for multiple projects?
Yes, each account has one active key that can be used across multiple projects. However, issuing a new key immediately invalidates the old one. Ensure all your projects use the same active key to avoid authentication issues. Monitor usage across all projects using this single key via the dashboard.
How do I rotate my API key?
You can issue a new key at any time from your account dashboard. Once a new key is issued, the old one stops working immediately. Update all your integrations to use the new key. This ensures secure access control without downtime, as the transition is instantaneous.
What formats are supported for output?
Supported response formats are mp3, wav, opus, flac, and pcm. Specify the desired format in the request body. Every generated file carries an inaudible watermark that marks it as synthetic speech. Choose the format that best fits your application's storage and playback requirements.
Is SSML supported in the API?
No, SSML is not supported. The API accepts plain text input up to 4096 characters. There are no phoneme dictionaries or custom pronunciation lexicons. You cannot control prosody or pauses via markup. Use text formatting or split requests to manage pacing if needed.
How do I handle long texts over 4096 characters?
Split the text into chunks of up to 4096 characters. Send each chunk as a separate request to the API. Receive the audio file for each chunk and join them sequentially. This ensures each request stays within the character limit while producing a continuous audio output.
What is the typical generation time?
Generation is roughly real-time, approximately 25 characters per second for long texts. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue. This ensures consistent processing but may introduce latency during high traffic periods.
Do I need an account to test the API?
Yes, you need an account to obtain an API key. Sign up via Google or email/password on /get-api-key/. Google sign-ups receive a $0.50 trial credit valid for 7 days. Email accounts start without trial credit. You need a key to authenticate and make requests.
First request
curl
curl https://api.ba11.info/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.ba11.info/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.ba11.info/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
The API uses standard Bearer token authentication. Include your unique key in the request header as Authorization: Bearer tts-.... Each account holds one active key at a time; generating a new key immediately invalidates the previous one.
This model simplifies credential management for large SaaS teams. You do not need to handle complex OAuth flows or rotate multiple tokens simultaneously. Secure storage of the single active key is sufficient for production environments.
Bearer Token Usage
Pass the key in the Authorization header of every request. The format is strictly Bearer tts-<your-key>. If the token is missing or incorrect, the API returns a 401 Unauthorized error.
The key grants access to all endpoints, including speech synthesis and voice listing. Treat it like a password; do not expose it in client-side code or public repositories.
- Header format:
Authorization: Bearer tts-... - One active key per account
- Invalidates previous key immediately upon rotation
Key Rotation
Generate a new key via the /get-api-key/ dashboard. The old key stops working instantly, ensuring no overlap in active credentials. This eliminates the need for dual-key rollout periods.
Rotate keys periodically or immediately after a suspected breach. Since only one key is active, the transition is atomic and requires no configuration changes in your integration.
Security Best Practices
Store keys in environment variables or a secure secrets manager. Use HTTPS for all API calls to prevent interception. Although the API is stateless, the key is the sole identifier for your billing account.
Monitor usage via the dashboard to detect unusual activity. Since billing is character-based, sudden spikes may indicate unauthorized use of your key.
- Use environment variables
- Store in secrets manager
- Monitor usage for anomalies
Speech Endpoint
Send POST requests to https://api.ba11.info/v1/audio/speech to generate audio from text. The endpoint accepts a JSON body with a maximum input length of 4,096 characters. For longer texts, split the input into chunks and join the resulting audio files sequentially.
Requests are processed sequentially, so under load, synthesis may queue behind previous tasks. Typical generation speed is roughly real-time, approximately 25 characters of text per second of audio generated.
POST /v1/audio/speech
The endpoint accepts standard JSON payloads. Use the site’s API key in the Authorization header.
JSON Body Structure
Include the model identifier, input text, voice preset, and desired output format. Optional parameters allow speed adjustment and language specification.
- model: "tts-1" or "tts-1-hd"
- input: string, max 4,096 characters
- voice: one of 8 presets
- response_format: mp3, wav, opus, flac, or pcm
- speed: 0.25–4.0
- language: optional ISO code
Required Fields
Every request must specify the model, input text, voice, and response format. The language field is optional; if omitted, the system guesses based on the script, defaulting to English for Latin text.
Voice Configuration
Select one of eight voice presets to define the synthetic voice character for your notifications. Options range from warm narrators to neutral news readers, ensuring consistent tone across multilingual interfaces.
Available Voice Presets
Choose from female voices like aria (warm narrator) or nova (bright, upbeat), and male voices such as atlas (neutral, news) or milo (friendly, conversational). Each voice is derived from licensed LibriTTS-R recordings.
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Speed Parameter Range
Adjust the playback speed between 0.25 and 4.0. This allows fine-tuning of audio duration for user interface elements or notification alerts without altering the voice characteristics.
Language Code Specification
Specify the ISO language code to ensure accurate pronunciation, especially for non-English Latin scripts which default to English otherwise. The API supports 23 languages, including Arabic, Chinese, German, Japanese, and Spanish.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Output Formats
The API supports five distinct audio formats to suit various playback environments. You select the output type via the response_format field in your request, which determines the encoding and file structure of the returned audio data.
MP3 Compatibility
MP3 is the default format, offering broad compatibility with web players and mobile applications. It provides efficient compression suitable for general notification delivery and interface audio where file size matters.
WAV Lossless Option
WAV delivers uncompressed audio, preserving the full fidelity of the synthetic voice. This format is ideal for systems that require raw audio data or need to perform further processing without decoding artifacts.
FLAC and OPUS Support
FLAC offers lossless compression, reducing file size while maintaining perfect audio quality. OPUS provides high-quality audio at lower bitrates, optimizing bandwidth usage for storage or playback.
Rate Limits
VoxGrid enforces a standard rate limit of 60 requests per minute for each API key. This throughput is designed to support consistent generation for multilingual user notifications and interface audio without requiring complex client-side pacing logic.
60 Requests Per Minute
Each active key processes up to 60 synthesis requests within a rolling one-minute window. Requests are processed sequentially, meaning long texts may take longer due to real-time generation speeds of approximately 25 characters per second.
Initial Limit for New Keys
New API keys start with a reduced limit of 10 requests per minute. This threshold applies until the first top-up is processed. Once a minimum $5 USDT (TRC-20) transfer is confirmed, the limit automatically increases to the standard 60 requests per minute.
Queue Behavior Under Load
Requests are processed one after another. Under heavy load, additional requests may wait in a queue before synthesis begins. Ensure your client handles HTTP 429 Too Many Requests errors gracefully by implementing exponential backoff rather than immediate retries.

Error Handling
Errors return standard HTTP codes with JSON bodies containing code and message fields. Client errors indicate issues with the request, such as invalid authentication, exceeding rate limits, or malformed input. Server errors suggest temporary infrastructure issues, for which you may retry with exponential backoff.
4xx Client Errors
Common 4xx responses include 401 (Unauthorized) for invalid or expired API keys, 429 (Too Many Requests) when the per-key limit of 60 requests per minute is exceeded, and 400 (Bad Request) for invalid model or voice parameters. Each response includes a descriptive message to help correct the input.
- 401: Invalid or revoked API key
- 429: Rate limit exceeded (60 req/min)
- 400: Invalid parameters or input text
5xx Server Errors
5xx errors, such as 503 Service Unavailable, indicate temporary server-side issues. Failed requests are free: if synthesis fails, the charge is returned in full. If synthesis fails due to a server error, the request is free, and you may retry immediately or after a short delay.
Retry Logic
For transient 5xx errors, implement exponential backoff with jitter. For 429 errors, wait until the rate limit window resets. Do not retry 4xx errors unless the client input is corrected.
- Use exponential backoff for 5xx errors
- Wait for rate limit reset on 429
- Retry max 3 times for transient errors
OpenAI SDK Integration
Leverage the official OpenAI SDKs by updating the base URL to https://api.ba11.info/v1. This allows your existing integration code to work without major refactoring, using the same request shape as the standard speech endpoint. Pass your API key via the Authorization header to authenticate each request.
Base URL Configuration
Set the client’s base URL to https://api.ba11.info/v1. This ensures all requests route through our infrastructure while maintaining compatibility with the official OpenAI SDKs.
Client Initialization
Initialize the OpenAI client with your specific API key (tts-...). The SDK handles the JSON serialization automatically, so you can pass parameters directly as you would for the standard speech endpoint.
Request Parity
The request structure mirrors the OpenAI speech endpoint exactly. Supported fields include model, input, voice, response_format, and speed. Use tts-1 or tts-1-hd for the model parameter.
- Base URL: https://api.ba11.info/v1
- Auth Header: Bearer tts-...
- Model: tts-1 or tts-1-hd
Curl Example
The following examples demonstrate standard request structures for the speech endpoint. Each snippet targets the base URL https://api.ba11.info/v1 and includes the required authentication header.
Use these patterns as a baseline for integrating the API into your notification pipelines or interface audio systems.
Basic Request
Send a POST request with your text input and model selection. The system processes the text and returns the audio file directly.
Voice Selection
Specify one of the eight preset voices, such as 'nova' or 'atlas', to define the vocal tone. The voice parameter accepts only the defined presets.
Format Specification
Select the output format using the response_format field. Choose from mp3, wav, opus, flac, or pcm depending on your storage and playback requirements.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Her consistent delivery helps users process important data quickly, especially in high-stress scenarios like payment failures or service disruptions.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- W3C WAI: making audio and video accessible
- ISO 639 language codes
- OpenAI API reference: create speech
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
- MDN: Web Speech API
- IETF RFC 7845: Ogg Opus
- Creative Commons Attribution 4.0
- LibriTTS-R paper (arXiv 2305.18802)
- Tether (USDT)
- Python documentation
