Complete API Reference for Text-to-Speech Synthesis

By ToonVoice API editorial team · Updated 2026-11-18

This guide provides the complete technical reference for the ToonVoice API, designed specifically for animation teams generating voice-overs for cartoons and animated videos. You will find exact endpoint structures, required headers, and parameter definitions needed to integrate synthetic speech directly into your production pipeline. Use this documentation to replace manual voice actor recordings with consistent, high-quality audio generated from your scripts.

We cover authentication, supported models, and output formats like MP3 and WAV. You will learn how to handle language detection, adjust speech speed, and manage rate limits. All examples use the standard OpenAI SDK shape, allowing you to switch base URLs and start generating audio immediately. This page is your single source of truth for building reliable TTS integrations.

Complete API Reference for Text-to-Speech Synthesis

Frequently asked questions

What is the base URL for the API?

The base URL is https://api.playabcdbet.com/v1. You send POST requests to the /audio/speech endpoint. This structure matches the OpenAI speech endpoint, allowing you to integrate easily into your existing animation production pipeline without learning a new URL scheme.

Can I use the OpenAI SDK?

Yes. The endpoint shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playabcdbet.com/v1 and providing your ToonVoice API key. This lets you leverage familiar client libraries for your cartoon voice-over generation.

How do I set the language?

Include the optional language field with an ISO code in your JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting it ensures accurate pronunciation for non-English languages like French, German, or Japanese.

What is the character limit per request?

Each request supports up to 4096 characters. For longer scripts, split your text into parts of this size and join the resulting audio files. This ensures consistent quality and prevents timeouts, keeping your animation voice-over generation smooth and reliable for your production team.

Can I stream the audio?

No. The API returns the complete audio file in the response after synthesis finishes. We do not support streaming, WebSocket connections, or real-time partial audio delivery. You must wait for the full file to be generated before proceeding with your animation timeline.

Do you support SSML?

No. The API accepts plain text input only. There is no support for SSML tags, phoneme dictionaries, or custom pronunciation lexicons. You control pacing and emphasis primarily through the speed parameter (0.25–4.0) and selecting the appropriate voice preset for your cartoon characters.

How do I handle rate limits?

You are limited to 60 requests per minute per key. Before your first top-up, the limit is 10 requests per minute. If you exceed this, requests may queue. Plan your batch generation for cartoon episodes accordingly to avoid delays in your voice-over pipeline.

What audio formats are supported?

We support mp3, wav, opus, flac, and pcm. Choose the format that best fits your animation software. MP3 is efficient for web delivery, while WAV or FLAC offers high quality for professional editing. All formats are generated via the same API endpoint.

First request

curl

curl https://api.playabcdbet.com/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.playabcdbet.com/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.playabcdbet.com/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

Getting Your API Key

Sound wave illustration for: Getting Your API Key

To start generating voice-overs for your animated projects, head to the /get-api-key/ page on playabcdbet.com. You can sign up quickly using your Google account or create a standard email-based account. This step creates your independent storefront account, separate from any other provider.

Sign Up on the Site

Sign Up on the Site

Registration is instant. If you use Google, you immediately receive a $0.50 free trial credit valid for 7 days, enough for roughly 50,000 characters. Email-based accounts start with a zero balance, ready for you to add funds via USTRC20 whenever you are ready to produce your first cartoon scene.

Locate Key in Dashboard

Locate Key in Dashboard

Once logged in, your dashboard displays your unique API key, current balance, and usage statistics. You will see a ready-to-use cURL example that you can copy directly into your animation pipeline script. This key is the only credential needed to authenticate your requests to the API.

  • Key format: tts-...

Revoke and Generate New Keys

You can issue a new API key at any time directly from the dashboard. When you generate a new key, the previous one stops working immediately. This feature is useful if you suspect your key was exposed in your animation studio's version control system.

Authentication

Sound wave illustration for: Authentication

To secure your requests, include a simple header in every API call. The header format is Authorization: Bearer YOUR_API_KEY. This token authenticates your identity and links usage to your account balance. Keep this key secure; anyone with it can generate speech and consume your credits.

Bearer Token Header

Include Authorization: Bearer <key> in your HTTP headers for every POST request to /v1/audio/speech. The key is a string starting with tts-. Ensure there are no extra spaces or quotes around the token value itself.

Single Active Key

Each account holds exactly one active API key at any time. If you generate a new key, the previous one becomes invalid immediately. This ensures that if a key is compromised, you can revoke access instantly without waiting for a manual approval process.

  • Only one key is valid per account simultaneously.

Key Rotation

Generate a new key from your dashboard anytime. The old key stops working the moment the new one is issued. This is useful for rotating credentials in your animation pipeline or if you suspect unauthorized usage.

  • Old key invalidates immediately upon new key creation.

Endpoint: POST /v1/audio/speech

Sound wave illustration for: Endpoint: POST /v1/audio/speech

The core of ToonVoice is the speech synthesis endpoint. Send your animation script here and receive a generated audio file. This endpoint handles the heavy lifting of converting your text into spoken dialogue for your cartoon characters.

Request Body Structure

Send a JSON object as the request body. The structure mirrors standard TTS APIs, making it easy to integrate using existing tools. You define the model, input text, voice, desired output format, and optional speed and language in this single payload.

Required Fields

You must provide the model ("tts-1" or "tts-1-hd"), the input text (up to 4096 characters), and the voice preset. These three fields are essential for generating any audio response.

  • model: "tts-1" or "tts-1-hd"
  • input: your script text
  • voice: one of the 8 available presets

Optional Parameters

Customize the output with response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0), and language (ISO code). If language is omitted, the system guesses it, defaulting to English for Latin script text.

  • response_format: mp3, wav, opus, flac, or pcm
  • speed: 0.25 to 4.0
  • language: optional ISO code

Supported Models

Sound wave illustration for: Supported Models

ToonVoice API offers two model presets, tts-1 and tts-1-hd, which utilize the same underlying synthesis engine. This consistency ensures that your animated characters maintain a uniform vocal quality across different production batches, regardless of whether you prioritize standard processing or enhanced clarity.

tts-1 Standard

The tts-1 model provides reliable, real-time generation speeds suitable for most cartoon voice-over needs. It processes text at roughly real-time speed, making it suitable for generating dialogue, though requests are processed sequentially and may queue under load.

tts-1-hd High Quality

Select tts-1-hd when you need slightly richer audio fidelity for key scenes or main characters. Both models use the same engine and price, so there is no difference in voice characteristics or quality between them.

Same Engine and Price

Both models share the exact same engine and pricing structure. You pay $0.01 per 1,000 characters regardless of which preset you choose. This simplifies your budget calculations, allowing you to switch between models for specific creative needs without incurring additional costs or changing your rate limit expectations.

Input Parameters

Sound wave illustration for: Input Parameters

Control the core behavior of your cartoon voice-overs by adjusting text length, voice character, and delivery speed. These parameters let you fine-tune the output to match your animation’s pacing without needing complex markup.

Text Input Limit

Each request accepts up to 4,096 characters of input text. This limit applies per API call, so longer scripts must be split into parts and the resulting audio files joined later.

Voice Selection

Choose from eight distinct presets like Aria for narration or Felix for promos. Every voice supports all 23 languages, allowing you to maintain consistent character tones across different episodes.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Speed Adjustment

Adjust speech rate between 0.25 and 4.0 to match the visual action. Slower speeds clarify dialogue, while faster rates suit rapid comedic sequences.

Input Parameters

Output Formats

Sound wave illustration for: Output Formats

To select the output format, include the response_format field in your JSON body. You can choose from mp3, wav, opus, flac, or pcm to match your animation pipeline’s needs.

MP3

MP3 is the default format. It provides a good balance between file size and quality, making it ideal for web playback and quick previews of cartoon scenes.

WAV

WAV offers uncompressed audio data suitable for professional audio editing workflows. This ensures no quality loss when you import the voice-over into your animation software for precise syncing.

OPUS, FLAC, PCM

OPUS provides efficient compression for streaming or bandwidth-constrained environments. FLAC offers lossless compression for archiving high-fidelity audio without increasing file size as much as WAV. PCM returns raw audio data, useful for direct processing in specialized audio engines.

Language Handling

Sound wave illustration for: Language Handling

ToonVoice supports 23 languages, allowing any voice preset to speak any supported language. The API automatically detects the language from the input text’s script, though you should set the language explicitly for non-English Latin text to ensure correct pronunciation.

Automatic Detection

The system identifies the language based on the characters provided. For example, Chinese characters trigger Chinese mode, while Cyrillic triggers Russian.

Manual ISO Code

You can explicitly set the language field with an ISO code (e.g., "de" for German). This overrides automatic detection and ensures consistent pronunciation even with mixed scripts.

Latin Script Default

If the text uses Latin script and no language is specified, the API defaults to English. For non-English Latin text (e.g., Spanish or French), you must set the language parameter to ensure correct accent and grammar.

  • Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
  • Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali

Rate Limits and Errors

Sound wave illustration for: Rate Limits and Errors

ToonVoice API enforces a rate limit of 60 requests per minute per API key. This ensures fair usage for animation teams generating multiple lines of dialogue. Requests are processed sequentially, so under heavy load, a request may wait in a queue before synthesis begins.

If you exceed the limit, the API returns a 429 status code. Failed requests due to server errors do not consume your character balance, ensuring you only pay for successful audio generation.

60 Requests Per Minute

Your API key allows up to 60 requests per minute. For accounts with no top-up yet, the limit is lower at 10 requests per minute. This applies to all synthesis requests, regardless of text length.

Requests are processed one after another. If you send many requests simultaneously, they queue up. Longer texts may take time to generate, roughly real-time speed (25 characters per second).

  • Limit: 60 requests/minute per key
  • New accounts (no top-up): 10 requests/minute
  • Processing is sequential under load

429 Too Many Requests

When you exceed the 60 requests/minute limit, the API responds with HTTP 429. Your request is rejected immediately, and no characters are deducted from your balance.

You can retry after a short wait. Consider splitting large scripts into smaller batches if you need to generate many lines quickly.

500 Server Errors

If the synthesis engine encounters an unexpected issue, it returns a 500 status code. These failures are free, meaning the character count is not charged to your account.

Retry the request after a brief pause. If errors persist, contact support via email.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. The FAQ section below addresses common questions about voice selection, language support, and character limits to help you keep generating audio efficiently.

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. MDN: Web Speech API
  3. Creative Commons Attribution 4.0
  4. OpenAI API reference: create speech
  5. LibriVox public-domain audiobooks
  6. Tether (USDT)
  7. openai-node on GitHub
  8. IETF RFC 7845: Ogg Opus
  9. FFmpeg documentation
  10. curl documentation
  11. Python documentation
  12. Node.js documentation

More on this site