API Documentation for Text-to-Speech Integration

By VoxGrid editorial team · Updated 2026-11-19

This documentation outlines the technical specifications for integrating VoxGrid’s text-to-speech API into multilingual SaaS notification systems. It details the endpoint structure, authentication protocols, and response formats required for reliable synthetic voice generation across large-scale user interfaces.

Designed for engineering teams managing high-volume audio delivery, this guide covers rate limits, error handling, and SDK integration. You will find concrete examples for curl requests and OpenAI SDK configuration, ensuring consistent character-based billing and seamless TRC-20 top-up workflows without unnecessary complexity.

API Documentation for Text-to-Speech Integration

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

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

Authentication

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

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

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

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

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

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

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

Rate Limits

Error Handling

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

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

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

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. W3C WAI: making audio and video accessible
  3. ISO 639 language codes
  4. OpenAI API reference: create speech
  5. LibriTTS-R corpus (OpenSLR 141)
  6. openai-python on GitHub
  7. MDN: Web Speech API
  8. IETF RFC 7845: Ogg Opus
  9. Creative Commons Attribution 4.0
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. Tether (USDT)
  12. Python documentation

More on this site