Frequently asked questions
What SDKs are supported?
The API follows the OpenAI speech endpoint shape, so the official OpenAI SDKs work by changing the base_url to https://api.z533.net/v1. We do not offer an official SDK of our own, nor a mobile SDK or WordPress plugin. You can also use plain HTTP requests with your Bearer token for authentication.
Do I need to install a specific package?
No specific package is required. Since the request format matches the OpenAI speech endpoint, you can use the standard OpenAI SDKs by simply updating the base_url. Alternatively, you can send standard HTTP POST requests with JSON bodies. There is no need to install proprietary libraries or extensions.
How do I handle long texts?
Split your text into parts of up to 4096 characters and send each part as a separate request. Then, join the returned audio files together. This ensures you stay within the character limit per request while generating complete audio for longer scripts or dialogue sequences.
Can I stream the audio?
No, we do not support streaming, WebSocket connections, or real-time partial audio. The API returns the complete audio file in the response after synthesis finishes.
Does the API support SSML?
No, the API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You provide plain text input, and the engine handles the synthesis. If you need specific pronunciation, you may need to adjust the text manually, as there are no emotion tags or SSML tags available.
How do I set the language manually?
Include the optional language field with an ISO code in your request. If not set, the language is guessed from the script, defaulting to English for Latin text. For non-English Latin-script text, you must explicitly set the language field to ensure correct synthesis.
What is the maximum text length?
The maximum text length per request is 4096 characters. If your script exceeds this limit, you must split it into smaller chunks. Each chunk is processed separately, and you will receive individual audio files that you can concatenate to form the final audio track.
How fast is the generation?
Generation is roughly real time on long texts, about 25 characters per second. Short phrases may take a few seconds. Requests are processed sequentially, so under load, a request may wait in a queue. Plan your generation timing accordingly to avoid delays in your pipeline.
Can I use the same key on multiple servers?
Yes, you can use the same API key on multiple servers or instances. Each account has one active key that you can use across different environments. If you issue a new key, the old one stops immediately, so ensure all your servers are updated to the new key.
What happens if the API is down?
We do not provide an SLA or uptime guarantee. If synthesis fails, the charge is returned in full. You can retry the request or check the status. Since there is no SLA, we recommend implementing retry logic in your application to handle potential transient failures.
Is there a webhook for completion?
No, there is no webhook for completion. The API is synchronous; you receive the audio file in the response after synthesis finishes. You must poll or wait for the response to get the audio data. There are no background notifications for when generation completes.
How do I generate audio in the background?
Since there are no webhooks, you must handle background generation in your own application. Send the request, wait for the response, and then process the audio asynchronously in your code. You can use standard threading or async tasks in your preferred language to manage the workflow.
Can I batch process requests?
You can send multiple requests, but they are processed one after another. There is no native batch endpoint. Monitor your rate limit of 60 requests per minute per key.
Do I need to handle audio concatenation?
Yes, if you split long texts into multiple requests, you must handle audio concatenation yourself. The API returns separate audio files for each chunk. You can use standard audio libraries in your language to join these files into a single track before delivering the final output to your users.
First request
curl
curl https://api.z533.net/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.z533.net/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.z533.net/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
AnimeVoice API uses standard bearer token authentication for all requests. Include your unique API key in the Authorization header of every call to https://api.z533.net/v1. This key acts as your single credential for generating audio and managing your account.
API Key header
Pass your key as Authorization: Bearer tts-.... The header must be included in every request to the speech endpoint and dashboard pages. Without this header, the API returns a 401 Unauthorized error.
Key management
Each account holds one active key. You can generate a new key at any time from the dashboard at /get-api-key/. The old key stops working immediately when the new one is issued, ensuring clean transitions if you suspect a leak.
- One key per account
- Instant rotation
- View in dashboard
Security basics
Store your key in environment variables rather than hardcoding it in client-side code. Since the API is designed for backend generation, keep the key secure on your server. Failed requests do not consume your character balance, but the key remains valid for retries.
- Use environment variables
- Secure backend storage
Endpoints
The API provides three core endpoints for generating audio and inspecting available resources. Use the speech endpoint to convert text into synthesized audio files, the voices endpoint to list available presets and supported languages, and the models endpoint to check engine details.
Speech generation
Send text to the speech endpoint to receive an audio file. The request must be a POST to /v1/audio/speech with a JSON body containing the model, input text, voice, and response format. You can adjust the speed between 0.25 and 4.0.
Voice listing
Retrieve available voices, languages, and formats using GET /v1/voices. This endpoint helps you verify which presets like Aria or Atlas are available for your animation characters before generating audio. Note that all 8 voices support all 23 languages.
Model info
Check available models with GET /v1/models. Both tts-1 and tts-1-hd use the same engine and pricing.
Request Parameters
Define the core parameters that control how your character’s voice is synthesized. You must specify the model, input text, and voice preset for every request to ensure consistent character performance across your animation or game project.
Model selection
Choose between "tts-1" or "tts-1-hd". Both use the same engine and price ($0.01 per 1,000 characters). Select "tts-1-hd" if you need higher fidelity for close-up dialogue, while "tts-1" is sufficient for background lines or distant effects.
Input text
Pass your script as the input field. The API accepts up to 4,096 characters per request. For longer monologues, split the text into chunks and join the resulting audio files. Spaces and punctuation count toward the character limit.
Voice selection
Select one of eight preset voices. Female voices like Aria or Nova offer clear, upbeat tones, while male options like Felix or Atlas provide energetic or neutral narration. These presets are designed to help animation startups quickly assign distinct character identities without custom training.
- 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 audio data in the format specified by the response_format parameter, defaulting to MP3. This format provides a practical balance between file size and audio quality, making it suitable for most web and mobile applications where storage efficiency matters alongside clear voice output.
MP3 output
MP3 is a supported format and offers a balance between file size and quality for most web and mobile applications. It is the default choice for generating character voice lines efficiently without excessive bandwidth usage.
WAV support
WAV provides uncompressed audio, preserving the exact fidelity of the synthesis engine. This format is ideal for post-production workflows where you need raw audio files to apply further effects or editing in your animation pipeline.
Opus and FLAC
Opus offers high-quality compression suitable for streaming or storage-constrained environments, while FLAC provides lossless compression for smaller file sizes than WAV without any quality loss. Note that we do not support streaming audio playback.
Choose Opus for efficient delivery in real-time game engines or low-bandwidth scenarios. Select FLAC when you need archival-quality audio that remains smaller than standard WAV files but retains every detail of the synthetic voice.
Rate Limits
Understanding rate limits ensures your animation pipeline runs smoothly without unexpected pauses. AnimeVoice API processes requests sequentially, meaning your voice lines generate one after another rather than in parallel bursts.
Requests per minute
Each API key allows 60 requests per minute under normal conditions. This limit applies to the POST /v1/audio/speech endpoint specifically.
Initial limits
New accounts start with a lower limit of 10 requests per minute until the first top-up is processed. This prevents sudden spikes from draining free trial credits too quickly.
Queue behavior
Requests are processed in order. If you send more than 60 requests in a minute, subsequent requests wait in a queue until capacity frees up. Short phrases may take a few seconds, while longer texts generate at roughly real-time speed.

Code Examples
The API mirrors the OpenAI speech endpoint, so existing libraries work with minimal configuration. You only need to update the base URL and provide your API key via the Authorization header.
Below are quick examples for generating audio files in common environments, helping you integrate voice lines into your animation or game projects immediately.
cURL example
Use this command to generate speech directly from your terminal. Replace the placeholder key and adjust parameters as needed for your specific voice and format requirements.
curl -X POST https://api.z533.net/v1/audio/speech-H "Authorization: Bearer YOUR_API_KEY"- `-d '{"model": "tts-1", "voice": "nova", "input": "Hello world", "response_format": "mp3"}'`
Python SDK
Install the official OpenAI Python package and point it to our base URL. This allows you to integrate TTS directly into your Python scripts.
pip install openaifrom openai import OpenAIclient = OpenAI(base_url='https://api.z533.net/v1', api_key='YOUR_KEY')
Node.js SDK
Configure the Node.js OpenAI client to use our endpoint. This is ideal for server-side generation in web games or backend services.
npm install openaiconst { OpenAI } = require('openai');const client = new OpenAI({ baseURL: 'https://api.z533.net/v1', apiKey: 'YOUR_KEY' });
Error Handling
Synthesis failures are free, so you won’t be charged for bad requests. However, network issues or invalid inputs can interrupt your workflow. Knowing how to handle these errors ensures your voice line generation stays smooth and cost-effective.
Common errors
Most errors stem from exceeding the 4,096 character limit per request or using an invalid voice name. If the text is too long, split it manually. Invalid parameters return a clear message. Failed requests are free.
- Invalid API key
- Text exceeds 4096 characters
- Unknown voice preset
- Rate limit exceeded
Retry logic
Implement exponential backoff for transient errors like 429 or 503. Since requests are processed sequentially under load, a request may wait in a queue. Wait a few seconds before retrying to avoid overwhelming the endpoint.
- Exponential backoff recommended
- Wait 1-2 seconds initially
- Retry up to 3 times
Status codes
Use standard HTTP status codes to determine next steps. A 200 OK means your audio file is ready. A 400 error indicates a problem with your request body that needs fixing before the next attempt.
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 429: Rate Limit
- 500: Server Error
Advanced Usage
The API offers fine-grained control over voice pacing and language handling to fit diverse animation workflows. You can adjust speech tempo and explicitly define languages to prevent mispronunciation in character dialogue.
Speed adjustment
Control the pacing of character dialogue using the speed parameter, accepting values from 0.25 to 4.0. A value of 1.0 represents normal speed. Use lower speeds for emotional pauses or higher speeds for rapid-fire banter.
Language detection
The system guesses the language from the script by default, but Latin-script text defaults to English. For non-English text in Latin script, always set the language field to the correct ISO code (e.g., 'ja' for Japanese) to ensure accurate pronunciation.
Text splitting
Each request supports up to 4096 characters of input text. For longer scripts, split your text into chunks, generate audio for each part, and join the resulting audio files. Failed requests are free, so splitting reduces financial risk for long scenes.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. While not the highest-fidelity option, the eight diverse voices provide clear, consistent narration suitable for RPGs and visual novels.
23 languages
Any voice speaks any of these languages.
