Frequently asked questions
How do I generate an API key?
Navigate to /get-api-key/ and sign up using Google or an email and password combination. The dashboard displays your active API key immediately. Each account holds one active key at a time. You can issue a new key at any time, which invalidates the previous one instantly.
What is the base URL for the API?
The API base URL is https://api.playvebet.com/v1. Use this endpoint for all requests. For example, send POST requests to https://api.playvebet.com/v1/audio/speech. This structure matches the OpenAI endpoint shape, allowing standard HTTP clients and compatible SDKs to connect directly.
Can I use the OpenAI Python SDK?
Yes. The API uses the same request shape as the OpenAI speech endpoint. Configure your OpenAI SDK by changing the base_url to https://api.playvebet.com/v1. Pass your PlayVeBet API key in the Authorization header. This allows seamless integration without modifying your existing code structure.
How do I set the voice parameter?
Include the voice parameter in your JSON body with one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. These voices support all 23 languages. You can retrieve the full list of available voices via the GET /v1/voices endpoint.
What happens if I exceed the rate limit?
The limit is 60 requests per minute per key. If you exceed this, subsequent requests will be queued or rejected. New accounts start with a 10 requests per minute limit. Requests are processed sequentially, so high volume may cause queuing delays beyond the limit.
Does the API support WAV format?
Yes. You can specify the response_format parameter as wav, mp3, opus, flac, or pcm. Set this field in your JSON request body. The API returns the audio file in the requested format. Failed requests do not incur charges regardless of the format used.
How do I handle long texts in requests?
Split your text into parts of up to 4096 characters. Send each part as a separate request. Receive the resulting audio files and join them programmatically. This ensures compliance with the character limit per request while allowing you to generate longer content.
What is the maximum character limit?
The maximum input length is 4096 characters per request. This limit applies to the input field in the JSON body. Spaces and punctuation count toward this total. For texts exceeding this limit, you must split the input into multiple requests.
Is SSML supported in the input text?
No. The API does not support SSML. It accepts plain text input. Custom pronunciation lexicons and phoneme dictionaries are also not available. The system processes the text directly without SSML tags. Use standard text formatting for your input.
How do I rotate my API key?
Issue a new key from your dashboard at any time. The new key becomes active immediately. The previous key stops working at once. You can generate a new key without downtime if you update your applications to use the new credential.
What does the 2400 character limit mean?
The API accepts up to 4096 characters per request. If you encounter a 2400-character limit, it likely stems from your client’s default settings or a specific implementation detail, not the API itself. Ensure your integration respects the documented 4096-character maximum for single requests to optimize efficiency.
Can I stream audio as it generates?
No. The API does not support streaming or WebSocket connections. Audio is returned as a complete file in the response. There is no real-time partial audio delivery. You must wait for the full synthesis to complete before receiving the audio data.
How do I specify the language code?
Include the language parameter with an ISO code in your JSON body. If omitted, the system guesses the language from the script. Latin text defaults to English. Set the language explicitly for non-English Latin-script text to ensure accurate synthesis.
What is the default response format?
The default response format is mp3. You can specify an alternative by setting the response_format parameter to wav, opus, flac, or pcm. If unspecified, the API returns mp3, ensuring compatibility with standard audio players. Note that the API does not support SSML or custom pronunciation lexicons, so format selection applies to the raw synthesized output.
First request
curl
curl https://api.playvebet.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.playvebet.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.playvebet.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 and Keys
Authentication for the PlayVeBet TTS API relies on a single active Bearer token per account. Developers must provision this key via the /get-api-key/ dashboard, where the current credential and usage metrics are displayed. The token authenticates all requests to the API base URL.
Generating API Keys
Create an account using Google Sign-In or email credentials. The dashboard displays your active key immediately upon registration. Only one key is active at any time; generating a new key invalidates the previous one instantly.
Bearer Token Usage
Include the key in the HTTP header as Authorization: Bearer tts-<your-key>. This header is required for all endpoints, including speech synthesis and voice listing. Ensure the key is transmitted securely over HTTPS.
Key Rotation Policy
Keys can be rotated at any time via the dashboard. Upon issuing a new key, the old one stops working immediately. This ensures quick revocation if a key is compromised, with no downtime for new keys.
Endpoint Configuration
The API operates on a strict RESTful structure accessible via https://api.playvebet.com/v1. All requests must target this base URL, ensuring compatibility with standard HTTP libraries and the official OpenAI SDKs when the base URL is overridden.
Base URL Structure
Use https://api.playvebet.com/v1 as the base endpoint for all API interactions. This base URL replaces the default OpenAI endpoint in your SDK configuration, allowing you to use the official OpenAI SDKs without modification to the request body shape.
Speech Endpoint Path
Send text-to-speech requests to POST /v1/audio/speech. This endpoint accepts JSON bodies containing the model, input, voice, and optional response_format or speed parameters. The API returns the generated audio file directly in the response body.
Voice Listing Endpoint
Retrieve available voices, supported languages, and audio formats by sending a GET request to /v1/voices. This endpoint provides the necessary metadata to correctly format your speech requests, including the valid voice IDs such as aria, nova, or atlas.
Request Parameters
The API requires specific parameters to generate audio correctly. You must define the model, input text, voice, and optional formatting options in the JSON body of your POST request. These fields determine the synthesis engine, audio quality, and output characteristics.
Proper configuration ensures consistent results across language learning applications. Verify that all inputs adhere to the defined constraints before submission to avoid processing delays or silent failures.
Model Selection Options
Select between 'tts-1' or 'tts-1-hd'. Both models use the same engine and pricing structure. The choice does not affect cost or engine quality; both models use the same engine and pricing.
The model field is required for every request. Using either value yields identical audio quality for standard use cases.
- Model values: 'tts-1', 'tts-1-hd'
Input Text Constraints
The 'input' field accepts a string of up to 4096 characters. Spaces and punctuation count toward this limit. Longer texts must be split into multiple requests and joined client-side.
If the text exceeds the limit, the request will fail. Ensure your application handles character counting before sending data to the endpoint.
- Maximum length: 4096 characters per request
Voice ID Assignment
Assign one of eight preset voices using the 'voice' field. Each voice has a distinct tone suitable for educational content. Examples include 'aria' for narration or 'atlas' for neutral delivery.
Optionally specify a 'language' ISO code if the text script does not clearly indicate the language. Without this, the system guesses the language, defaulting to English for Latin script.
- Supported voices: aria, nova, luna, sage, felix, milo, atlas, orion
- Optional language parameter for disambiguation
Response Handling
The API returns the synthesized audio file directly in the response body, eliminating the need for secondary polling or file retrieval steps. Depending on your chosen response_format, the payload is delivered as MP3, WAV, OPUS, FLAC, or PCM data, ensuring compatibility with standard educational media players and LMS integrations.
Audio Format Output
Generated audio is returned in the response and not stored. Clients receive the raw audio bytes immediately upon successful synthesis, allowing for direct streaming or local caching within your application's memory or temporary storage.
Select the format that best matches your language learning platform's requirements. MP3 offers efficient compression for web delivery, while WAV or FLAC provides uncompressed quality for high-fidelity pronunciation exercises.
- Supported formats: mp3, wav, opus, flac, pcm
- No server-side storage of generated audio files
- Direct binary response body
Status Code Interpretation
A 200 OK status indicates successful synthesis. The response body contains the audio data. Other 2xx codes confirm successful processing of the request.
Non-2xx codes indicate errors. Failed requests are free, and any pre-charged amounts are returned in full. Check the response headers for specific error details.
Error Message Structure
Errors follow a standard JSON structure with an error object containing type and message fields. This structure aids in automated error handling within your integration.
Common errors include invalid API keys, input text exceeding 4096 characters, or unsupported voice IDs. Review the message to correct the request parameters before retrying.
- JSON error response format
- Includes
typeandmessagefields - Failed requests incur no charge
SDK Integration Examples
PlayVeBet’s API mirrors the OpenAI speech endpoint structure, allowing direct integration with existing OpenAI SDKs. This compatibility enables rapid deployment for language learning applications by requiring only a base URL adjustment when using the official OpenAI SDKs.
Python SDK Configuration
Import the OpenAI library and initialize the client with your Bearer token. Set the base_url to https://api.playvebet.com/v1 to route requests through our infrastructure. This ensures all synthesis calls utilize the correct PlayVeBet endpoint.
- Use
openai.OpenAI(base_url="https://api.playvebet.com/v1", api_key="tts-...") - Call
client.audio.speech.create()with standard parameters - Response includes audio bytes directly in the response body
Node.js SDK Setup
Install the openai npm package and configure the client similarly. Pass the API key and override the base URL to point to the PlayVeBet service. This method supports both synchronous and asynchronous text-to-speech generation for web applications.
- Initialize with
new OpenAI({ baseURL: 'https://api.playvebet.com/v1', apiKey: 'tts-...' }) - Supports Promise-based audio generation
- Compatible with standard Node.js event loops
Base URL Override Method
The core integration strategy relies on overriding the default base URL. Since the request shape matches the OpenAI standard, developers can switch providers by changing a single configuration variable. This simplifies testing and production deployments for educational tools.
- Change
base_urltohttps://api.playvebet.com/v1 - Retain standard
model,voice, andinputfields - No custom SDK installation required

Curl Command Examples
To generate audio directly from the command line, send a POST request to the speech endpoint with your bearer token and desired parameters. The API returns the audio file in the specified format, allowing for immediate integration into language learning workflows without complex SDK dependencies.
Basic Speech Request
Use this command to convert text into speech using the default model and voice. Replace YOUR_API_KEY with your actual key and input_text with the content you wish to synthesize. The response will contain the audio binary data.
- POST https://api.playvebet.com/v1/audio/speech
- Headers: Authorization: Bearer YOUR_API_KEY
- Body: {"model": "tts-1", "input": "Hello world", "voice": "aria"}
Speed Adjustment Request
Adjust the playback speed between 0.25 and 4.0 to match learner pacing. This parameter is useful for creating clear audio for language acquisition exercises. The API processes the request synchronously, ensuring consistent audio quality regardless of speed variations.
- --data '{"model": "tts-1", "input": "Fast speech", "voice": "nova", "speed": 1.5}'
Format Selection Request
Specify the output format using the response_format field. Supported formats include mp3, wav, opus, flac, and pcm. Choosing the appropriate format ensures compatibility with your existing audio processing pipelines and reduces bandwidth usage for language learning applications.
- --data '{"model": "tts-1", "input": "Audio file", "voice": "sage", "response_format": "mp3"}'
Rate Limiting Details
Rate limits are enforced per API key to ensure stable service for language learning applications. After the first top-up, each key allows 60 requests per minute. This throughput supports typical educational workflows without requiring complex batching logic.
Requests Per Minute Limit
After the first top-up, each key allows 60 requests per minute. This limit applies to all synthesis requests, including those with varying speeds or formats. Exceeding this threshold results in standard HTTP 429 responses.
Pre-Top-Up Limit
Accounts without an active top-up operate under a reduced limit of 10 requests per minute. This ensures fair usage during the initial trial phase or before financial verification is complete.
Queuing Behavior
Requests are processed sequentially. Under heavy load, a request may wait in a queue before synthesis begins. This behavior ensures deterministic processing order but may increase latency for bulk generation tasks.
Troubleshooting Common Issues
The API returns a 401 Unauthorized status when the Bearer token is missing, expired, or incorrect. Verify that your key begins with "tts-" and matches the active key in your PlayVeBet dashboard. If you rotated your key, ensure the old one is no longer in use, as rotation invalidates previous credentials immediately.
Input Text Length Errors
The API rejects payloads exceeding 4096 characters, returning a 413 error. Each request must contain a single text segment within this limit. For longer content, implement client-side splitting to divide the input into chunks, process each separately, and concatenate the resulting audio files.
- Maximum input length: 4096 characters per request.
- Spaces and punctuation count toward the character limit.
- Split long texts client-side before sending requests.
Network Timeout Handling
Short phrases typically generate within a few seconds, but longer texts may take longer due to real-time processing speeds (approximately 25 characters per second). Under load, requests queue sequentially, which may extend response times beyond standard thresholds. Implement exponential backoff for retries to handle temporary delays without overwhelming the endpoint.
- Set HTTP timeout to at least 30 seconds for short texts.
- Expect longer latency for texts exceeding 1000 characters.
- Retry with backoff if the queue is full.
Invalid API Key Errors
Ensure the Authorization header uses the format Bearer tts-.... Keys are case-sensitive and must match the active key in your PlayVeBet account dashboard. If you issued a new key, the previous one stops working immediately. Use the dashboard’s "Revoke" or "Generate" functions to manage active credentials.
- Header format:
Authorization: Bearer tts-<your-key>. - One active key per account; rotation invalidates old keys instantly.
- Check dashboard for current key status and balance.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. Empower your global team with intuitive language learning tools that bridge cultural gaps and accelerate collaboration.
23 languages
Any voice speaks any of these languages.
