Frequently asked questions
Which SDKs are officially supported?
The API is compatible with the official OpenAI SDKs. Since the request shape matches the OpenAI speech endpoint, you can use any OpenAI SDK by adjusting the base URL. No proprietary SDK is provided.
Do I need to install a specific library?
No specific library is required. You can use the standard OpenAI SDK or plain HTTP requests. The API follows the same request structure as the OpenAI speech endpoint, allowing immediate compatibility with existing OpenAI client libraries.
How do I change the base URL in OpenAI SDK?
Configure your OpenAI SDK client to use https://api.ao999.info/v1 as the base URL. This allows the official SDK to route requests correctly to our endpoint without requiring code changes to the request body structure.
What is the maximum text length per request?
Each request supports a maximum of 4096 characters in the input field. For longer texts, split the content into chunks of up to 4096 characters and join the resulting audio files after synthesis completes successfully.
Can I send audio in WAV format?
Yes. The response_format parameter accepts mp3, wav, opus, flac, and pcm. You can specify wav in your request to receive uncompressed audio data directly in the response body.
Does the API return metadata with audio?
The response returns the audio file directly. Request metadata, including time, characters, and status, is kept for billing purposes but is not included in the audio response payload itself.
How do I handle a 429 Too Many Requests error?
The limit is 60 requests per minute per key. Implement exponential backoff or queue your requests. If you are under the 10 requests/minute limit, wait until the rate window resets or top up your balance.
Is the API endpoint HTTP or HTTPS?
The endpoint is HTTPS: https://api.ao999.info/v1/audio/speech. All requests must be sent over a secure connection to ensure authentication and data integrity during transmission.
Can I use the same key for multiple projects?
Yes. Each account has one active API key that can be used across multiple projects or services. You can issue a new key at any time, which invalidates the previous one immediately.
What happens if the server is down?
If synthesis fails, the charge is returned in full. There is no SLA or uptime guarantee. Failed requests are free.
Do I get a receipt for each request?
Request metadata (time, characters, status) is kept for billing. However, there are no invoices or individual receipts generated per request. You can monitor usage and balance directly on your dashboard.
Is the API versioned?
Yes. The endpoint is versioned at /v1/audio/speech. This ensures predictable behavior and allows for future updates without breaking existing integrations that rely on the current request structure.
Can I test with a dry run mode?
No dry run mode exists. Every request consumes characters from your balance unless the synthesis fails. Use the free trial credit or small text inputs to test costs and latency before production use.
How do I regenerate my API key?
Navigate to the /get-api-key/ page in your account. You can issue a new key at any time. The old key stops working immediately when the new one is activated.
First request
curl
curl https://api.ao999.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.ao999.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.ao999.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
Authentication relies on a single Bearer token sent via the Authorization header. This key authorizes all requests to the https://api.ao999.info/v1 base URL. The token is issued upon account creation and must be included in every HTTP call to distinguish your NPC audio generation requests.
Bearer Token Header
Include your key as Authorization: Bearer tts-<your_key> in the HTTP header. This standard format ensures compatibility with existing OpenAI SDKs by simply changing the base_url. Keep this token secure in your build environment or CI/CD pipeline to prevent unauthorized audio generation charges.
Key Issuance Limits
Each account maintains exactly one active API key. There is a limit of 60 requests per minute (10 per minute before the first top-up), and there is only one key per account. This simplifies permission management for freelance audio engineers managing multiple game projects, as you do not need to track multiple tokens.
- Only one key is active per account
Key Revocation
You can issue a new key at any time via the dashboard. When a new key is generated, the previous key stops working immediately. This allows you to rotate credentials quickly if you suspect exposure without waiting for a manual expiration period.
Endpoint Specification
The API provides three primary endpoints for integration. The speech synthesis endpoint accepts text and returns audio. The voices and models endpoints provide metadata for configuration.
All endpoints require a valid Bearer token in the Authorization header. Base URL is https://api.ao999.info/v1.
Speech Synthesis POST
Endpoint: POST /v1/audio/speech. Accepts JSON body with model, input, voice, response_format, and optional speed/language. Returns binary audio data. Max input is 4096 characters.
Failed requests return zero charge. The endpoint processes requests sequentially; under load, queuing may occur.
- -
model: "tts-1" or "tts-1-hd" -input: string, max 4096 chars -voice: one of 8 presets -response_format: mp3, wav, opus, flac, pcm -speed: 0.25–4.0 -language: optional ISO code
Voices List GET
Endpoint: GET /v1/voices. Returns available voice presets, supported languages, and formats. Useful for dynamic UI generation in game engines.
Each voice has a unique ID. All voices support all 23 listed languages.
- - Returns voice ID, name, gender, description - Lists supported languages - Shows available response formats
Models List GET
Endpoint: GET /v1/models. Returns available model identifiers. Currently supports "tts-1" and "tts-1-hd", which share the same engine and pricing.
Use this to verify available models before synthesis requests.
Request Parameters
For NPC dialogue, input text is limited to 4096 characters per request. Spaces and punctuation count toward this total. Longer lines must be split client-side and concatenated.
Select one of eight deterministic voices based on role type. Each voice supports any of the 23 supported languages, allowing consistent character audio across multilingual projects.
Input Text Constraints
Each API call accepts a maximum of 4096 characters in the input field. This limit applies to the raw string, including all spaces and punctuation. If a dialogue line exceeds this, split the text into chunks, synthesize them separately, and join the resulting audio files in your asset pipeline.
Text encoding should be UTF-8. Ensure no trailing whitespace causes unnecessary character billing, as every character counts toward your 1M characters/$10 rate.
Voice ID Selection
Choose a voice ID that matches the NPC's archetype. Available presets include female voices (aria, nova, luna, sage) and male voices (felix, milo, atlas, orion). All voices support all 23 listed languages.
For consistent character voices, always specify the voice parameter explicitly. Do not rely on auto-detection for critical assets, as Latin-script text defaults to English.
- 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 Format Codes
Specify the desired audio format via the response_format parameter. Supported formats are mp3, wav, opus, flac, and pcm. Choose based on your engine's requirements; WAV and FLAC are lossless, while MP3 and OPUS offer compression.
PCM provides raw linear audio, useful for debugging or specific middleware integrations. The default format is MP3 if not specified.
- mp3: compressed, widely supported
- wav: lossless, standard for games
- opus: efficient compression
- flac: lossless compression
- pcm: raw linear audio
Speed and Language
Control generation speed and language explicitly for consistent NPC dialogue. Adjust timing to match character animations or speech patterns without altering the audio engine's base performance characteristics.
Speed Multiplier Range
Set the speed parameter between 0.25 and 4.0. Values below 1.0 slow the output; values above 1.0 accelerate it. This allows precise synchronization with game engine timelines without post-processing artifacts.
Language ISO Codes
Pass the language field with a valid ISO code from the supported list (e.g., 'en', 'de', 'ja'). All 8 voices can speak all 23 supported languages. Explicitly setting this prevents misinterpretation of dialect-specific phonemes.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
Auto-Detection Behavior
If language is omitted, the API guesses the language from the script. Latin script defaults to English. For non-English text using Latin characters, always specify the language code to ensure correct pronunciation.
Example Requests
These examples demonstrate how to generate NPC dialogue audio using the standard tts-1 model. The API accepts text up to 4096 characters and returns binary audio data directly in the response body, allowing seamless integration into game engines or audio pipelines.
cURL Command Line
Use cURL to send a POST request to the speech endpoint. Replace YOUR_API_KEY with your active token and TEXT_HERE with your NPC dialogue string. The example below requests an MP3 file using the 'aria' voice.
- curl -X POST "https://api.ao999.info/v1/audio/speech" \<br> -H "Authorization: Bearer YOUR_API_KEY" \<br> -H "Content-Type: application/json" \<br> -d '{"model": "tts-1", "input": "Halt! Identify yourself.", "voice": "aria", "response_format": "mp3"}' \<br> --output npc_halt.mp3
Python OpenAI SDK
The official OpenAI Python SDK works by overriding the base_url. Initialize the client with your API key and point it to https://api.ao999.info/v1. This allows you to use standard Audio methods while accessing our specific voice presets and pricing.
Node.js Axios Example
Use Axios to handle the JSON payload and stream the binary response. Ensure you set the responseType to arraybuffer to prevent corruption of the audio file. This method is ideal for server-side generation of asset libraries before packaging.

Response Handling
The synthesis endpoint returns the generated audio as a binary stream in the response body. The content type matches the requested response_format, such as audio/mpeg for MP3 or audio/wav for uncompressed WAV. This allows direct piping into game engines or audio pipelines without intermediate file writes.
Binary Audio Return
Audio data is returned in the response body. For NPC dialogue, this output ensures consistent asset generation. The binary payload contains the audio file, ready for ingestion by Unity, Unreal, or custom audio middleware.
JSON Error Codes
Failures return a JSON object with an error field containing a code and message. This structure allows programmatic handling of issues like insufficient balance or invalid voice IDs. Failed requests do not consume characters from your balance.
- Invalid request: 400 Bad Request
- Authentication failure: 401 Unauthorized
- Rate limit exceeded: 429 Too Many Requests
Status Code Interpretation
A 200 OK status indicates successful synthesis, with the audio body following. Use 200 to trigger asset import steps in your build pipeline. Other codes indicate specific failures requiring retry logic or parameter correction.
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 429: Rate Limit
Rate Limits
Your API key allows 60 requests per minute under normal conditions. This limit applies to the POST /v1/audio/speech endpoint and is enforced per key, not per IP or project.
Requests Per Minute
Standard accounts process up to 60 synthesis requests per minute. Each request consumes one unit of this quota regardless of input text length or output format.
Pre-Topup Limits
Accounts with no balance or only free trial credit are limited to 10 requests per minute. This restriction remains active until a USDT top-up is confirmed on the TRON network.
Queue Behavior
Error Handling
Errors return standard HTTP status codes with a JSON body describing the issue. Failed synthesis requests are free, ensuring you are not charged for invalid inputs or network interruptions.
Always validate your request payload before sending. The API provides clear error messages for common issues like unsupported voices, oversized text, or insufficient funds.
Invalid Voice ID
Requesting a voice that does not exist returns a 400 Bad Request. Ensure the voice field matches one of the eight available presets: aria, nova, luna, sage, felix, milo, atlas, or orion.
Text Too Long
Each request supports a maximum of 4096 characters in the input field. Exceeding this limit triggers a 400 error. Split longer dialogue into multiple requests and join the resulting audio files client-side.
Insufficient Balance
If your account balance is lower than the cost of the request (based on character count), the API returns a 402 Payment Required error. No charge is applied. Top up via USDT (TRC-20) to resume service.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Unlike our model, Azure requires a monthly Azure subscription and potentially higher minimum spend commitments.
23 languages
Any voice speaks any of these languages.
