API Documentation for Text-to-Speech Integration

By Vocaltoons editorial team · Updated 2026-11-18

This documentation helps animation studios integrate high-quality synthetic voices into their production workflows. You will find clear instructions on generating audio files for storyboards and prototypes using our REST API. The guide covers authentication, endpoint structures, and parameter details tailored for cartoon creators who need consistent character voices without complex licensing.

We provide practical examples for integrating with the OpenAI SDK or using direct curl commands. You will learn how to manage API keys, handle rate limits, and select from eight distinct voice presets. This reference material ensures you can quickly prototype dialogue and maintain audio consistency across your animated projects.

API Documentation for Text-to-Speech Integration

Frequently asked questions

What is the base URL for the API?

The API base URL is https://api.playyowestogel.com/v1. You send POST requests to https://api.playyowestogel.com/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are also available at this base path for retrieving voice details and model information.

How do I generate an API key?

Sign up on the /get-api-key/ page using Google or an email and password. Your account page displays your active API key, balance, and usage stats. You can issue a new key at any time, which immediately stops the old one.

Can I use the OpenAI SDK with this API?

Yes. The request shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playyowestogel.com/v1 and using your site-specific key. This allows seamless integration for your animation workflow without learning a new client.

What are the rate limits for the API?

The limit is 60 requests per minute per key. New accounts start with 10 requests per minute until the first top-up is processed. Requests are processed sequentially, so under load, a request may wait in a queue before synthesis begins.

Which audio formats are supported?

You can request audio in mp3, wav, opus, flac, or pcm formats. Specify the desired format using the response_format field in your JSON body. This flexibility allows you to choose the best codec for your animation pipeline or prototype needs.

How do I handle failed requests?

If synthesis fails, the charge is returned in full. You do not pay for failed requests. Simply retry the request with the same parameters after addressing any potential errors, such as exceeding the character limit or network issues.

What is the maximum character limit?

Each request supports up to 4096 characters of input text. For longer scripts, split your text into parts of this size and join the resulting audio files. Spaces and punctuation count toward this character limit.

Can I change the voice after sending the request?

No. You must specify the voice parameter (e.g., aria, nova, felix) in the request body before sending. The API generates audio based on the specified voice at the time of the request. There is no post-processing voice change feature.

Is the API synchronous or asynchronous?

The API is synchronous. You send a POST request and receive the audio file in the response. There is no WebSocket or streaming endpoint for partial audio. You wait for the synthesis to complete before receiving the data.

How do I specify the language?

Pass the optional language field with an ISO code in your request. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Set it explicitly for non-English Latin-script text to ensure accuracy.

What happens if I exceed the rate limit?

Requests may queue or fail if you exceed 60 requests per minute. New accounts are limited to 10 requests per minute until the first top-up. Exceeding limits does not incur extra charges but may delay generation due to sequential processing.

Do I need to pay for each request?

Yes, you pay $0.01 per 1,000 characters. Failed requests are free. You must have a positive balance, funded via USDT on the TRON network, to generate audio. The free trial provides $0.50 credit for new Google sign-ups.

Can I use the API for batch processing?

Yes, but requests are processed one after another. For large batches, split long texts into 4096-character chunks and join the audio files. Be mindful of the 60 requests per minute limit to avoid queuing delays during high-volume production.

How do I revoke my API key?

You do not manually revoke keys. Instead, issue a new API key from your account page. The old key stops working immediately when the new one is active. This allows you to invalidate access instantly without waiting for a timeout.

First request

curl

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

Authentication

Sound wave illustration for: Authentication

Vocaltoons uses standard Bearer token authentication to secure your API requests. Include your unique key in the HTTP header as Authorization: Bearer tts-<your-key>. This single key grants access to all endpoints and ensures your usage is billed correctly to your account balance.

Generating Your API Key

Generating Your API Key

Create your key by signing in at /get-api-key/ using Google or email. The dashboard displays your active key, current balance, and a ready-to-use cURL example. Accounts created with email start without trial credit, while Google sign-ins receive $0.50 valid for 7 days.

  • One active key per account
  • Available immediately after signup
  • Visible on the dashboard

Key Management and Revocation

Key Management and Revocation

If your key is compromised, generate a new one from the dashboard. The old key stops working immediately, while the new one becomes active. This ensures your animation project data remains secure without downtime. You can issue a new key as often as needed.

  • Instant invalidation of old keys
  • No service interruption
  • Unlimited key rotations

Endpoints Overview

Sound wave illustration for: Endpoints Overview

The API provides three core endpoints to manage voice generation and configuration. The primary endpoint handles speech synthesis, while the others list available voices and model details. This structure allows animation studios to quickly integrate TTS into their pipeline without complex setup.

Each endpoint returns specific data relevant to character voice selection and technical requirements. Use the list endpoints to verify available voices before sending synthesis requests, ensuring your character audio matches the desired tone and language.

POST /v1/audio/speech

Sends text to generate audio. Accepts a JSON body with model, input text, voice, and format options. Returns the audio file directly.

Text is limited to 4096 characters per request. Longer scripts must be split and concatenated by the client.

  • Base URL: https://api.playyowestogel.com/v1
  • Method: POST
  • Response: Audio file (mp3, wav, etc.)

GET /v1/voices

Lists all 8 available voice presets and their supported languages. Returns metadata including voice ID, gender, and style description.

Use this to select the right voice for your cartoon characters. Voices include Aria, Nova, Luna, Sage, Felix, Milo, Atlas, and Orion.

  • Returns voice ID and name
  • Supported languages list
  • Voice style descriptions

GET /v1/models

Returns available model versions, currently tts-1 and tts-1-hd. Both use the same engine and price.

Select the model that fits your budget and quality needs for each scene.

  • Model ID
  • Name
  • Price per 1M characters

Request Parameters

Sound wave illustration for: Request Parameters

To generate consistent character voices for your animations, select either tts-1 or tts-1-hd. Both models use the same engine and pricing, allowing you to prototype quickly without worrying about format compatibility for your storyboard scripts.

Model Selection (tts-1, tts-1-hd)

Use tts-1 for standard quality or tts-1-hd for higher fidelity. Both incur the same rate of $10 per million characters. Choose based on your final production needs versus prototype speed.

Input Text and Length Limits

Send up to 4096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split your text into parts and join the resulting audio files sequentially.

  • Maximum input: 4096 characters
  • Characters include spaces and punctuation
  • Split long texts manually for best results

Voice and Language Selection

Assign one of eight preset voices to maintain character consistency. The system guesses language from Latin script text (defaulting to English), but you should explicitly set the language field for non-English content to ensure accurate pronunciation.

  • 8 voice presets available
  • Any voice speaks any of 23 supported languages
  • Set language explicitly for non-English Latin text

Response Formats

Sound wave illustration for: Response Formats

Every generated audio file carries an inaudible watermark marking it as synthetic speech. The API returns the audio file directly in the response body, meaning no long-term storage occurs. Generated audio is not stored by the service; it is simply returned for your immediate use in animation pipelines.

You can choose from five formats to match your studio’s post-production workflow. Failed requests return the error details without charging your balance, ensuring you only pay for successful synthesis.

Supported Audio Formats

Select the output format that best fits your rendering pipeline. The API supports mp3, wav, opus, flac, and pcm. Choose mp3 for efficient storage, wav for uncompressed quality, or opus for low-bandwidth delivery.

Each format preserves the audio fidelity of the selected model. The choice does not affect the character count or pricing, which remains $0.01 per 1,000 characters regardless of the format.

  • mp3: Compressed, widely compatible
  • wav: Uncompressed, high quality
  • opus: Efficient, low bandwidth
  • flac: Lossless compression
  • pcm: Raw, uncompressed data

JSON Response Structure

The response returns the audio binary directly if successful. For debugging, you can inspect the standard HTTP status codes. The request metadata is kept for billing purposes but not the audio itself.

If you need to parse the response in your animation software, the binary stream is the primary payload. Use the response headers to verify the content type matches your selected format.

Error Handling Codes

Standard HTTP status codes indicate the result of your request. A 200 OK means the audio was generated successfully. Use these codes to automate your pipeline’s error handling.

If synthesis fails, the charge is returned in full. Common errors include invalid parameters or rate limits. Check the response body for specific details to adjust your script or voice settings.

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 429: Rate Limit Exceeded
  • 500: Internal Server Error

Rate Limits and Quotas

Sound wave illustration for: Rate Limits and Quotas

Synthesis requests are processed sequentially, meaning your TTS queue processes one audio file at a time. During peak usage, requests may wait in a queue before generation begins, so plan your character voice renders accordingly.

60 Requests Per Minute

Each API key allows up to 60 requests per minute. This limit applies to the POST /v1/audio/speech endpoint. If you need to generate multiple character lines quickly, ensure your script respects this ceiling to avoid 429 errors.

Initial Limit for New Accounts

New accounts start with a reduced limit of 10 requests per minute. This applies until you complete your first top-up. Once you add funds via USDT on the TRON network, the full 60 requests per minute capacity is unlocked immediately.

Handling Queue Waits

Since requests are processed one after another, longer texts or high traffic can cause delays. For animation workflows, generate short phrases first to test voice consistency, then batch larger scripts. Failed requests incur no charge, so retrying on timeout is safe.

Rate Limits and Quotas

SDK Integration

Sound wave illustration for: SDK Integration

The API mirrors the OpenAI speech endpoint structure, allowing you to reuse existing OpenAI SDKs with minimal configuration. Simply update the base_url to point to our infrastructure, enabling seamless integration into your animation pipeline without learning a new client library.

This compatibility ensures that developers familiar with OpenAI’s tools can quickly switch to Vocaltoons for character voice generation. The consistent request shape means your existing code handles audio synthesis just as it does for other TTS services, reducing onboarding time for your team.

OpenAI SDK Compatibility

Use the official OpenAI SDK by pointing it to our endpoint. This approach leverages familiar libraries, making it easy to integrate text-to-speech into your Python or Node.js projects without significant refactoring.

  • Compatible with standard OpenAI client libraries
  • No custom SDK required
  • Familiar request/response patterns

Base URL Configuration

Set your SDK’s base_url to https://api.playyowestogel.com/v1. This directs all API calls to our infrastructure while maintaining the standard /v1/audio/speech path structure used by the OpenAI API.

Ensure your API key is included in the Authorization header as Bearer <your-key>. This token authenticates your requests and tracks your character usage against your account balance.

  • base_url: https://api.playyowestogel.com/v1
  • Header: Authorization: Bearer tts-...

Example Code Snippets

Here is a basic Python example using the OpenAI SDK: ```python from openai import OpenAI client = OpenAI( base_url="https://api.playyowestogel.com/v1", api_key="tts-your-api-key" ) audio = client.audio.speech.create( model="tts-1", voice="nova", input="Hello, this is a test voice for animation.", response_format="mp3" ) audio.write_to_file("output.mp3") ``` This snippet demonstrates sending text and receiving an MP3 file directly to your local drive for immediate use in your storyboard prototypes.

For debugging, ensure the voice name matches one of the eight available presets. If you encounter a 400 error, verify that your text input is under 4096 characters and that the language code is set if the text is not in English.

  • Use tts-1 or tts-1-hd for model
  • Set voice to a valid preset like nova or aria
  • Specify response_format (mp3, wav, opus, flac, pcm)

Curl Example

Sound wave illustration for: Curl Example

Use cURL to verify your API key works before building your animation pipeline. This quick command sends a short script to the speech endpoint and saves the result as an MP3 file.

Basic Request Command

Replace YOUR_API_KEY with your key from /get-api-key/. The model tts-1 is sufficient for most prototype narration. Save the output to a local file for immediate review in your animation software.

  • curl -X POST https://api.playyowestogel.com/v1/audio/speech \
  • -H "Authorization: Bearer YOUR_API_KEY" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Hello, world.", "voice": "nova"}' \
  • -o output.mp3

Sending Audio File

The response body is the raw audio data when successful. Redirecting output to a file (e.g., -o) avoids corrupting your terminal. Use formats like mp3 or wav depending on your editing workflow.

Debugging Common Errors

If you see a 429 error, you have exceeded 60 requests per minute. Check your key’s usage stats. A 401 error means the key is invalid or revoked. Ensure you are sending valid JSON.

  • Check rate limits if requests queue up.
  • Verify JSON syntax for the request body.
  • Ensure text does not exceed 4096 characters.

Data Privacy in API

Sound wave illustration for: Data Privacy in API

When you send text to our API, it is processed solely to generate the requested audio file. The input is not repurposed for other services or stored indefinitely once the audio is delivered. This ensures that your dialogue scripts and story notes remain private during the synthesis process.

Input Text Usage

Your text is used exclusively to produce the final audio output. Once the synthesis is complete, the input text is not retained for other uses, keeping your creative assets secure.

Metadata Retention

We keep request metadata, including the timestamp, character count, and status, strictly for billing and usage verification. This data is not used for any other purpose and helps you track your animation project costs accurately.

No Training Data Storage

Your input text is not used to train our models. Generated audio is returned in the response and not stored on our servers for later training, ensuring your unique character voices and scripts remain yours.

  • Input text used only for immediate synthesis
  • Metadata kept for billing purposes only
  • No input data used for model training
  • Generated audio not stored for training

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Our studio transforms your startup's vision into captivating animated experiences that delight and engage your target audience.

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. ISO 639 language codes
  3. curl documentation
  4. Node.js documentation
  5. FFmpeg documentation
  6. TRON developer hub: TRC-20
  7. OpenAI API reference: create speech
  8. MDN: Web Speech API
  9. openai-node on GitHub
  10. Tether (USDT)
  11. Python documentation
  12. openai-python on GitHub

More on this site