Frequently asked questions
Does the official OpenAI SDK work?
Yes. The API endpoint matches the OpenAI speech endpoint shape, so the official OpenAI SDKs work by changing the base URL. You simply point the SDK to our API base URL and use your VocalWave key. This works for Python, Node.js, and other languages supported by the OpenAI SDK without code modifications.
How do I change the base URL?
Set the base URL to https://api.playbet177.com/v1. When using the OpenAI SDK, update the configuration to point to this address. Your requests will then route to our text-to-speech engine. Ensure you use your valid Bearer token in the Authorization header for authentication during these requests.
What is the character limit?
Each request supports up to 4096 characters of input text. Spaces and punctuation count toward this limit. If your text exceeds this length, you must split it into smaller parts. Generate audio for each part separately and join the resulting audio files to create the final output.
Can I stream audio?
No. The API does not support streaming, WebSockets, or real-time partial audio. You send a POST request with your text and receive the complete audio file in the response. This synchronous approach ensures consistent delivery of the generated speech without the complexity of managing streaming connections.
Is SSML supported?
No. The API does not support SSML, phoneme dictionaries, or custom pronunciation lexicons. You provide plain text input, and the engine synthesizes it directly. If you need specific pronunciation adjustments, you must use standard spelling within the 4096-character limit of each request to the endpoint.
How do I split long texts?
Split your text into chunks of up to 4096 characters. Send each chunk as a separate POST request to the speech endpoint. Once you receive the audio files for all parts, join them sequentially to create the complete audio file. This ensures no data loss or truncation occurs.
What happens if I exceed rate limits?
You are limited to 60 requests per minute per key (10 per minute before the first top-up). Requests are processed sequentially, so under load, your request may wait in a queue. If you exceed the limit, you will receive an error response indicating the rate limit was hit.
Do you have a mobile SDK?
No. We do not offer an official mobile SDK. You can use the standard OpenAI SDK or plain HTTP requests from any platform that supports them. Since the API is REST-based, you can integrate it into iOS, Android, or any other mobile application using standard networking libraries.
Is there a WordPress plugin?
No. There is no official WordPress plugin for VocalWave. You must integrate the API directly into your WordPress site using custom code or a custom plugin. You can use the OpenAI SDK or HTTP requests to send text and receive audio files, then embed them as needed.
Can I use this API in OBS?
Yes, indirectly. Since the API returns audio files via HTTP, you can generate audio files and load them into OBS as media sources. You cannot stream audio directly from the API into OBS, but you can pre-generate clips and play them using OBS standard media input features.
How do I regenerate my API key?
Issue a new key from your account dashboard. When you generate a new key, the old one stops working immediately. You can issue a new key at any time. Ensure you update your applications with the new key to maintain uninterrupted service for your text-to-speech requests.
What audio formats are available?
You can choose from mp3, wav, opus, flac, and pcm formats. Specify the desired format in the response_format field of your request. Each format serves different use cases, from compressed web audio to lossless quality. Select the format that best fits your production workflow and storage requirements.
Can I set a custom speed?
Yes. You can adjust the speech speed between 0.25 and 4.0. Set the speed parameter in your request to control how fast the voice speaks. This allows you to match the pacing of your content, whether you need slower narration or faster delivery for dynamic videos.
First request
curl
curl https://api.playbet177.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.playbet177.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.playbet177.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
Secure your account with a single active Bearer token. Include it in the HTTP header as Authorization: Bearer tts-.... This key authenticates all requests to the API base URL.
Bearer Token Format
The token starts with the prefix tts- followed by unique alphanumeric characters. Pass it in every request header to identify your account and track usage against your balance.
API Key Management
Each account holds one active key visible on the /get-api-key/ dashboard. The key is tied to your specific site account (playbet177.com).
- View current key and usage stats instantly
- One active key per account at any time
Key Revocation
Issuing a new key immediately invalidates the previous one. The old key stops working at once, ensuring no concurrent usage from potentially compromised tokens.
Endpoints
The VocalWave API exposes three core endpoints for generating and managing speech assets. The primary synthesis endpoint accepts text and voice parameters to return audio files, while the metadata endpoints provide details on available voices and model configurations.
POST /v1/audio/speech
This endpoint processes your input text and returns an audio file. Send a JSON body containing the model, input, voice, and response_format. The API handles the synthesis and returns the binary audio data or an error object.
GET /v1/voices
Retrieve the list of eight available voice presets, their supported languages, and available output formats. This endpoint helps you verify which voices are currently active and compatible with your target languages before making synthesis requests.
- Returns voice ID, name, gender, and supported languages.
- Lists available
response_formatoptions: mp3, wav, opus, flac, pcm.
GET /v1/models
Fetch the list of available models, including tts-1 and tts-1-hd. This endpoint confirms the engine versions and their associated pricing tiers, allowing you to select the appropriate model for your quality and cost requirements.
Parameters
Configure the synthesis engine and audio output structure using three primary parameters. The model choice determines voice quality, while the voice preset selects the specific timbre. Finally, the response format defines the container type for the generated audio file.
Model Selection: tts-1 vs tts-1-hd
Select "tts-1" or "tts-1-hd"; both use the same engine and price. Both models use the same underlying engine and incur identical pricing per character, allowing you to switch based on your quality needs without cost penalties.
Voice Presets
Choose from eight distinct voice presets optimized for content creation. Female voices include Aria (warm narrator), Nova (upbeat), Luna (storytelling), and Sage (instructional). Male options feature Felix (energetic promo), Milo (conversational), Atlas (news), and Orion (documentary).
- Female: aria, nova, luna, sage
- Male: felix, milo, atlas, orion
Response Format Options
Specify the audio container format using the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. Select the format that best integrates with your existing video or streaming pipeline.
Request Body
The request body requires a JSON object containing the text to synthesize, the model identifier, the voice preset, and the desired audio format. Each field is mandatory except for the optional language code, which allows you to override automatic script detection.
Ensure your input adheres to the character limits and speed constraints defined below.
Input Text Limit: 4096 Chars
Submit a maximum of 4096 characters per request. Spaces and punctuation count toward this limit. For longer scripts, split the text into chunks and join the resulting audio files sequentially.
The typical generation speed is roughly real-time (25 characters per second), though short phrases may take a few seconds to process.
- Maximum input length: 4096 characters
- Characters include spaces and punctuation
- Split longer texts into multiple requests
Speed Control: 0.25–4.0
The speed parameter accepts values between 0.25 and 4.0, allowing you to slow down narration or accelerate dialogue. This is useful for adjusting voiceover timing without editing the audio file.
Requests are processed sequentially, so higher speeds may slightly increase queue wait times under load.
- Minimum speed: 0.25x
- Maximum speed: 4.0x
- Adjusts playback rate only
Optional Language Code
You can pass an optional ISO language code (e.g., en, ja, de) to specify the language. If omitted, the system guesses the language from the script; Latin script defaults to English.
Use this field for non-English Latin-script text to ensure correct pronunciation and intonation.
Voices support 23 languages, including Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
- ISO 639-1 code
- Optional override
- Defaults to English for Latin script
Code Examples
Use the provided examples to integrate VocalWave into your TTS pipeline. The API accepts standard JSON bodies, allowing you to switch between direct HTTP calls and managed SDKs with minimal code changes.
Each example demonstrates a complete request cycle, from setting the bearer token to handling the audio response. Ensure your client library supports multipart or binary response handling for the selected format.
cURL Command
Send a direct POST request to the speech endpoint. Replace YOUR_API_KEY with your active token from the dashboard. This method requires no external libraries and is ideal for quick testing or scripting in bash environments.
The response returns the raw audio file. Save it directly to disk or pipe it to another process. Remember that the input text must not exceed 4096 characters.
- Replace {api-key} with your actual key.
- Set the desired voice, model, and language.
- Specify the response format (mp3, wav, etc.).
OpenAI Python SDK
Install the official OpenAI Python package. Configure the base URL to point to our API endpoint instead of OpenAI's servers. This allows you to use familiar SDK methods for speech generation.
Pass your text and voice parameters using the same structure as the OpenAI API. The SDK handles authentication and response parsing automatically, returning the audio file as bytes.
- Set base_url to https://api.playbet177.com/v1
- Use tts-1 or tts-1-hd for the model.
Node.js Example
Use any standard HTTP client like axios or node-fetch. Construct the request with the correct headers and JSON body. The API returns the audio data, which you can write to a file or stream to a player.
Ensure you handle potential rate limits and errors gracefully. The SDK approach simplifies this by providing built-in retry logic and error types.
- Import your preferred HTTP client library.
- Set Authorization header with Bearer token.
- Parse the binary response for audio playback.

Rate Limits
VocalWave enforces a strict rate limit of 60 requests per minute per API key. This cap ensures stable synthesis performance. If you exceed this threshold, the API returns a 429 Too Many Requests error, and no characters are charged for the failed attempt.
Before your first top-up, new accounts are limited to 10 requests per minute. This allows you to verify integration quality with the free trial credit without overwhelming the queue. Once you add USDT (TRC-20), your limit increases to the standard 60 RPM.
60 Requests Per Minute
Each active API key supports up to 60 requests per minute. This limit applies to all POST /v1/audio/speech calls. Exceeding this limit results in a 429 error, ensuring fair usage for all developers on the same infrastructure.
- Limit: 60 requests/minute/key
- Error: 429 Too Many Requests
- Cost: Free if synthesis fails
10 Requests Before Top-Up
New accounts start with a 10 requests per minute limit. This lower threshold allows you to test the API with your free $0.50 trial credit. Top up via USTRC-20 to unlock the full 60 RPM capacity.
- New accounts: 10 RPM
- Requires USDT top-up
- No minimum spend
Queue Handling
Requests are processed sequentially. Under heavy load, your request may wait in a queue before synthesis begins. Typical speed is roughly real-time (25 characters per second), but short phrases may take a few seconds to generate. Be prepared for slight latency during peak usage.
Since requests are queued, ensure your client handles timeouts gracefully. Failed requests are free: if synthesis fails, the charge is returned in full.
- Sequential processing
- Latency possible under load
- Refunds on failure
Error Codes
VocalWave returns standard HTTP status codes to indicate request outcomes. Most errors are immediate, allowing your application to retry or adjust parameters without consuming credits.
400 Bad Request
Returned when the JSON body is malformed, the text exceeds 4096 characters, or the voice model is invalid. The response includes a message detailing the specific field that failed validation.
- Check input text length and encoding.
- Verify voice ID exists in GET /v1/voices.
401 Unauthorized
Occurs if the Bearer token is missing, incorrect, or revoked. Since each account holds only one active key at a time, ensure you are using the latest key from your dashboard.
- Regenerate key if compromised.
- Check Authorization header format.
429 Too Many Requests
Triggered when you exceed 60 requests per minute. New accounts start with a 10 requests/minute limit until the first top-up is processed. Implement exponential backoff to handle queue delays gracefully.
- Retry with increasing delay.
- Monitor rate limit headers.
FAQs
This guide covers the essential integration steps for the VocalWave API, ensuring you can generate speech assets efficiently for your VTuber or streaming content. The API follows a standard structure compatible with existing tooling, allowing you to swap in the base URL and begin synthesis immediately.
Does the OpenAI SDK work?
Yes. The request shape matches the OpenAI speech endpoint. You can use the official OpenAI SDKs by simply changing the base_url to https://api.playbet177.com/v1 and providing your VocalWave API key. This works for Python, Node.js, and other supported languages without code modifications.
How to handle long texts?
The API limits each request to 4,096 characters. To generate audio for longer content, split your text into chunks of this size, send separate requests, and join the resulting audio files in your post-production workflow.
What is the base URL?
Use https://api.playbet177.com/v1 as your base URL. All endpoints, including POST /v1/audio/speech, GET /v1/voices, and GET /v1/models, are prefixed by this domain.
Can I use WebSockets?
No. The API is synchronous and returns the final audio file in the response body. There is no streaming, WebSocket support, or real-time partial audio delivery. Requests are processed sequentially, so queueing may occur under load.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Your first request works instantly, with no waiting for model training or quality assurance checks.
23 languages
Any voice speaks any of these languages.
Sources and further reading
- Wikipedia
- FFmpeg documentation
- ISO 639 language codes
- Python documentation
- IETF RFC 7845: Ogg Opus
- OpenAI API reference: create speech
- LibriVox public-domain audiobooks
- Node.js documentation
- W3C WAI: making audio and video accessible
- curl documentation
- LibriTTS-R paper (arXiv 2305.18802)
- LibriTTS-R corpus (OpenSLR 141)
