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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
languageexplicitly for non-English Latin text
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
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.

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-1ortts-1-hdfor model - Set
voiceto a valid preset likenovaoraria - Specify
response_format(mp3, wav, opus, flac, pcm)
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
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.
23 languages
Any voice speaks any of these languages.
