Frequently asked questions
What is the API endpoint?
Send a POST request to https://api.playtoto155.com/v1/audio/speech with a JSON body containing your text and parameters. You can also use GET /v1/voices to list available voices and GET /v1/models to check model details. This endpoint structure mirrors the OpenAI speech API for easy integration.
How do I authenticate?
Include your API key in the request header as Authorization: Bearer tts-... . Each account holds one active key; issuing a new one immediately invalidates the old one. You can generate and view your key on the /get-api-key/ page after signing in with Google or email.
Which models are available?
Two models are available: tts-1 and tts-1-hd. Both use the same engine and pricing structure. Select either based on your quality needs, as the underlying synthesis process is identical. The model parameter is required in your JSON request body to specify which version to use.
What is the character limit?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. For longer texts, split your content into chunks of 4096 characters or less and join the resulting audio files. Failed requests do not consume this limit or incur charges.
How do I set the language?
Pass the optional language parameter with an ISO code, such as en, es, or de. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English Latin-script texts like French or Dutch.
Can I change the speed?
Yes, use the speed parameter with a value between 0.25 and 4.0. The default speed is 1.0. Adjusting this allows you to make speech faster or slower to fit your project’s timing needs. This parameter works with all available voices and models without affecting audio quality significantly.
What happens if I exceed rate limits?
The limit is 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 or fail. Failed requests are free: if synthesis fails, the charge is returned in full.
Does the API return metadata?
The response returns the generated audio file directly. Request metadata like time, characters, and status is kept for billing purposes but is not included in the audio response. You can track usage and balance on the /get-api-key/ page. Generated audio is not stored after the response.
How do I handle large texts?
Split your text into parts of up to 4096 characters each. Send each part as a separate request and join the resulting audio files. This ensures you stay within the character limit per request. The system processes requests sequentially, so plan your queue accordingly for long documents.
Is the OpenAI SDK compatible?
Yes, the endpoint shape matches the OpenAI speech endpoint. You can use official OpenAI SDKs by changing the base_url to https://api.playtoto155.com/v1 and using your site’s key. This allows you to leverage existing code and libraries without significant refactoring for your text-to-speech integration.
What audio formats are supported?
You can choose from mp3, wav, opus, flac, and pcm via the response_format parameter. Select the format that best suits your application’s requirements. All formats are generated from the same engine. The choice does not affect the price or the character count charged to your account.
How do I rotate my API key?
Issue a new key from the /get-api-key/ page. The new key becomes active immediately, and the old one stops working at once. This ensures secure access management. You can generate a new key as often as needed without any additional cost or downtime for your applications.
What is the default voice?
You must provide a voice parameter from the eight presets. Common choices include aria for narration or atlas for news. If you omit the voice parameter, the behavior depends on the SDK implementation, but specifying it is recommended.
Can I use custom voices?
No, custom voice cloning is not offered. You must choose from the eight available presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices are based on licensed recordings from LibriTTS-R and LibriVox. You cannot upload your own voice or design custom voices for your projects.
First request
curl
curl https://api.playtoto155.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.playtoto155.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.playtoto155.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
The WordCaster API uses standard Bearer token authentication. Include your unique API key in the request header as Authorization: Bearer tts-... for every call.
Each account maintains one active key. You can generate a new key at any time, and the previous key becomes invalid immediately.
Bearer token usage
Pass your key via the Authorization header. The format is Bearer tts-<your-key>. This works with the OpenAI SDK by setting the base URL to https://api.playtoto155.com/v1.
Key management
Your key is visible on the /get-api-key/ dashboard alongside your balance. There is no limit to how many keys you can issue, but only the most recently generated one remains active.
Key rotation
Generate a new key from your dashboard when needed. The old key stops working instantly, ensuring no overlap or confusion during deployment changes.
Endpoints
The API exposes three primary endpoints for generating audio, listing available voices, and checking model versions. Each endpoint follows a standard RESTful pattern, allowing you to integrate directly with your preferred HTTP client or SDK.
Requests are authenticated via the Authorization header. Ensure your key is valid and has sufficient balance before sending requests.
Speech generation endpoint
Send POST requests to /v1/audio/speech with your text and voice selection. The endpoint returns audio files in formats like MP3, WAV, or Opus. Text is limited to 4096 characters per request.
Failed requests do not incur charges. The API processes requests sequentially, so high load may introduce slight delays in generation.
- Endpoint: POST /v1/audio/speech
- Response formats: mp3, wav, opus, flac, pcm
- Max input: 4096 characters
Voices list endpoint
Use GET /v1/voices to retrieve all 8 voice presets, supported languages, and available formats. This helps you select the right voice for your project before generating audio.
Voices are compatible with all listed languages. If no language is specified, the API guesses based on the text script.
- Endpoint: GET /v1/voices
- Returns voice IDs, languages, and formats
- 8 presets: aria, nova, luna, sage, felix, milo, atlas, orion
Models endpoint
Call GET /v1/models to verify available TTS models. Currently, tts-1 and tts-1-hd are supported, offering the same engine and pricing.
This endpoint confirms the current model versions available for your account, ensuring compatibility with your integration.
- Endpoint: GET /v1/models
- Models: tts-1, tts-1-hd
- Same engine and pricing
Request parameters
To generate speech, specify the model as "tts-1" or "tts-1-hd"; both use the same engine and pricing. Your input text must not exceed 4096 characters per request, with spaces and punctuation counted toward the limit. For longer texts, split the content and join the resulting audio files manually.
Model selection
The API accepts "tts-1" or "tts-1-hd" in the model field. Both options utilize the identical synthesis engine and incur the same charge of $10 per million characters, regardless of which model you select.
Input text limits
Each request supports a maximum of 4096 characters. This limit includes all spaces, punctuation, and special characters. If your text exceeds this length, divide it into smaller chunks and concatenate the resulting audio files after generation.
Voice and language fields
Select one of eight preset voices via the voice parameter. The language field is optional; if omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accuracy for non-English Latin-script inputs.
Available voices include female presets like Aria and Nova, and male presets like Felix and Milo. These voices can speak any of the 23 supported languages, including Arabic, Chinese, and Swahili.
- Aria: warm, clear narrator
- Felix: energetic, promo
- Nova: bright, upbeat
- Atlas: neutral, news
Response formats
The API returns audio files in various formats depending on your response_format parameter. You can choose between MP3, WAV, Opus, or FLAC. Each format serves different use cases, from web delivery to high-fidelity storage.
Selecting the right format balances file size and quality. MP3 offers compression for easy web sharing, while WAV and FLAC preserve lossless audio for professional applications. Opus provides efficient compression for modern web standards.
MP3 output
MP3 is the default format for most web applications. It provides good audio quality with smaller file sizes. This makes it ideal for delivering speech to browsers or mobile apps without excessive bandwidth usage.
WAV output
WAV files are uncompressed and preserve the full audio quality. They are suitable for editing software or voiceovers requiring lossless audio. Use this format when you need the original audio data without compression artifacts.
Opus and FLAC support
Opus offers efficient compression suitable for modern web standards. FLAC provides lossless compression, reducing file size while maintaining audio integrity. Both formats are valid options depending on your storage and playback needs.
cURL example
Use cURL to test the API directly from your terminal. The endpoint accepts a JSON payload with your text, chosen voice, and desired audio format.
This method is ideal for quick validation before integrating into your no-code workflows or custom scripts.
Basic request structure
Send a POST request to https://api.playtoto155.com/v1/audio/speech with your Bearer token in the header.
Include the model (e.g., "tts-1"), input text, voice, and response_format in the JSON body.
Ensure the text does not exceed 4096 characters.
- Authorization: Bearer tts-...
Sending audio data
Specify your preferred output format such as mp3, wav, opus, or flac.
The API returns the audio file directly in the response body.
Longer texts should be split into chunks under the character limit to ensure proper synthesis.
Handling responses
A successful response contains the audio binary data.
If synthesis fails, the charge is returned, and an error code is provided.
Save the response body to a file to verify the generated speech.

OpenAI SDK integration
Integrate the WordCaster API into your projects using the official OpenAI SDKs by simply overriding the base URL. This allows you to leverage familiar code structures while accessing our text-to-speech engine without learning a new client library.
Configure the client to point to https://api.playtoto155.com/v1 and provide your API key. The SDK handles the HTTP requests, letting you focus on passing text and voice parameters.
Base URL configuration
Set the base_url parameter in your SDK client to https://api.playtoto155.com/v1. This directs all API calls to our infrastructure while maintaining compatibility with the standard OpenAI request shape.
Client initialization
Initialize the SDK client using your API key (starting with tts-...). Pass the configured base URL during initialization. This single setup step enables all subsequent speech generation calls.
Method usage
Call the audio.speech.create method with your text, selected voice, and desired format. The SDK returns the audio file directly, allowing you to save it immediately.
- Use
modelset to "tts-1" or "tts-1-hd" - Specify
voicefrom the 8 available presets - Set
response_formatto mp3, wav, opus, flac, or pcm
Error handling
The API returns standard HTTP status codes to indicate success or failure. A 200 OK response contains the audio file, while other codes signal specific issues. You should check the response body for a JSON object containing a code and message field to understand the exact cause of the failure.
Handling errors gracefully ensures your application remains robust during synthesis. By checking for specific error codes, you can decide whether to retry the request, adjust parameters, or alert the user. This section outlines the most common issues you might encounter.
Common error codes
The API uses standard HTTP status codes. A 400 Bad Request indicates invalid parameters, while a 401 Unauthorized means your API key is missing or incorrect.
- 400: Bad Request - Invalid JSON or missing fields.
- 401: Unauthorized - Invalid or expired API key.
- 500: Internal Server Error - Temporary service issue.
Rate limit errors
You are limited to 60 requests per minute per key. If you exceed this, requests may queue or fail. New accounts start with a limit of 10 requests per minute until the first top-up is processed.
- 429: Too Many Requests - Exceeded rate limit.
- Retry-After header indicates seconds to wait.
Invalid input errors
Input text must not exceed 4096 characters. If the text is too long, you will receive a 400 error. Ensure the voice ID is one of the eight available presets and the language code is valid if specified.
- 400: Text exceeds 4096 characters.
- 400: Invalid voice ID or language code.
Rate limits
Understanding request volume helps you plan your integration strategy. Our API enforces strict rate limits to ensure stable performance for all users, especially when processing bulk text-to-speech tasks.
60 requests per minute
Each API key is limited to 60 requests per minute. This cap applies to the /v1/audio/speech endpoint and ensures fair usage across the network.
Initial 10 requests limit
New accounts without a top-up start with a lower limit of 10 requests per minute. This allows you to test the service before scaling up your usage.
Queue behavior
Requests are processed sequentially. Requests are processed sequentially, so under load a request may wait in a queue.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Each voice is based on licensed recordings from LibriVox, ensuring clear, professional audio without licensing complexity.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- W3C WAI: making audio and video accessible
- FFmpeg documentation
- ISO 639 language codes
- Tether (USDT)
- LibriTTS-R paper (arXiv 2305.18802)
- IETF RFC 7845: Ogg Opus
- openai-node on GitHub
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- Python documentation
