API Documentation and Quickstart Guide for Text-to-Speech

By AnimeVoice API editorial team · Updated 2026-11-19

This documentation guides animation startups and game developers through the AnimeVoice API. You will find clear instructions for generating character voice lines using simple text-to-speech requests. We cover authentication, available endpoints, and supported audio formats so you can integrate synthetic voices into your production pipeline quickly.

Use this guide to understand rate limits, error handling, and code examples in Python or Node.js. Whether you are building a prototype or scaling character dialogue, we provide the technical details you need. The API follows a familiar request shape, allowing you to use standard SDKs with minimal configuration changes.

API Documentation and Quickstart Guide for Text-to-Speech

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

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

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

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

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

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

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

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

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

Rate Limits

Code Examples

Sound wave illustration for: 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 openai
  • from openai import OpenAI
  • client = 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 openai
  • const { OpenAI } = require('openai');
  • const client = new OpenAI({ baseURL: 'https://api.z533.net/v1', apiKey: 'YOUR_KEY' });

Error Handling

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

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

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. Node.js documentation
  3. FFmpeg documentation
  4. ISO 639 language codes
  5. openai-node on GitHub
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. W3C WAI: making audio and video accessible
  8. Creative Commons Attribution 4.0
  9. curl documentation
  10. IETF RFC 7845: Ogg Opus
  11. Tether (USDT)
  12. Python documentation

More on this site