Frequently asked questions
What is the first step to integrate the API?
Sign up on /get-api-key/ using Google or email to receive a Bearer token. Use this key in the Authorization header for POST requests to https://api.playvebet.com/v1/audio/speech. The endpoint accepts JSON bodies with model, input, voice, and response_format fields, enabling immediate integration into your language learning workflow.
Do I need to install a specific SDK?
No proprietary SDK is required. The API follows the standard OpenAI request shape, allowing you to use official OpenAI SDKs by changing the base_url to https://api.playvebet.com/v1. Alternatively, you can use plain HTTP requests. This ensures compatibility with your existing infrastructure without additional dependencies.
How do I handle audio data in Python?
Send a POST request to the speech endpoint with your text and parameters. The response contains the audio file directly. You can process this binary data using standard Python libraries like requests or httpx. Since no official SDK exists, handle the HTTP response body to store or stream the audio.
Can I use the API in a browser environment?
Yes, you can call the API directly from browser JavaScript. Send a POST request to the endpoint with your API key in the Authorization header. Be aware of CORS policies and ensure your key is secure if exposed client-side. The API returns audio files that can be played via standard HTML5 audio elements.
What happens if the API is slow?
Requests are processed sequentially, so under load, a request may wait in a queue. Typical speed is roughly real time, but short phrases take a few seconds. Failed requests are free, ensuring you are not charged for delays or errors. Monitor your queue status if building time-sensitive language learning features.
How do I detect language automatically?
If the language field is omitted, the API guesses the language from the script. Latin script defaults to English. For non-English Latin text, explicitly set the language parameter to the ISO code. This ensures accurate synthesis for your multilingual language learning content without manual detection logic.
Is the API suitable for real-time apps?
No streaming or WebSocket support exists for real-time partial audio. Requests are processed one after another, introducing latency under load. While typical speed is real-time for long texts, short phrases may take seconds. Use this API for pre-generated audio in language learning workflows rather than live interaction.
How do I manage multiple voices?
Call GET /v1/voices to retrieve the list of eight available presets. Select from female voices like aria or nova, or male voices like felix or milo. Pass the chosen voice ID in the request body. You can switch voices dynamically in your language learning app to provide diverse narration styles.
What is the best format for mobile apps?
MP3 is widely supported and efficient for mobile applications. You can also choose WAV, OPUS, FLAC, or PCM via the response_format field. MP3 offers a good balance between quality and file size for language learning content. Ensure your mobile client supports the selected format for seamless playback.
Can I split long texts programmatically?
Yes, split input text into parts of up to 4096 characters per request. Synthesize each part separately and join the resulting audio files. This approach handles longer language learning lessons or stories efficiently. The API does not handle splitting automatically, so implement this logic in your backend or client code.
How do I handle API key expiration?
Issue a new key from your account dashboard at any time. The old key stops working immediately upon issuing the new one. There is no fixed expiration date; keys remain active until replaced. Update your language learning app configuration with the new Bearer token to maintain uninterrupted service.
What is the maximum speed setting?
The speed parameter accepts values between 0.25 and 4.0. Adjust this to control the speech rate for language learners. Faster speeds may reduce comprehension, while slower speeds aid learning. Set the speed value in the request body to tailor the audio output to your specific educational use case.
Does the API work with React Native?
Yes, use standard HTTP fetch or libraries like axios to call the API. Send a POST request to the speech endpoint with the required JSON body. Handle the binary audio response appropriately for playback in React Native. Since no official SDK exists, rely on standard network requests compatible with your environment.
How do I verify the audio file integrity?
The API returns the audio file directly in the response. Verify integrity by checking the response status code and ensuring the file downloads completely. Generated files include an inaudible watermark marking them as synthetic. Use standard checksums or file size checks in your language learning app to confirm successful synthesis.
Prerequisites for Integration
To integrate PlayVeBet’s TTS API into language learning applications, developers must first secure an API key. Registration is available via the /get-api-key/ page using Google or an email account. The system provides a single active key per account, which can be regenerated immediately if compromised, ensuring secure access control for your startup’s infrastructure.
API Key Acquisition Process
Sign up on the /get-api-key/ page using Google or email. Upon creation, you receive a Bearer token starting with 'tts-'. Accounts created with email and password start without trial credit; Google sign-ins receive $0.50 valid for 7 days. Keys are managed per site, so ensure you register on playvebet.com.
- Register via /get-api-key/ using Google or email
- Receive a unique Bearer token (tts-...) immediately
- Google sign-in includes $0.50 trial credit; email accounts do not
- Keys can be regenerated anytime, invalidating the previous key instantly
Development Environment Setup
Configure your environment to send POST requests to https://api.playvebet.com/v1/audio/speech. The endpoint accepts JSON bodies with fields like 'model', 'input', and 'voice'. Standard HTTP libraries or the OpenAI SDK (with adjusted base_url) work effectively. Ensure your runtime supports JSON serialization and binary audio response handling.
- Set base_url to https://api.playvebet.com/v1
- Use standard HTTP POST to /audio/speech
- Support JSON request bodies and binary audio responses
- Compatible with OpenAI SDKs by overriding the base URL
Network Connectivity Requirements
Ensure your server can reach https://api.playvebet.com over HTTPS (port 443). The API enforces a rate limit of 60 requests per minute per key. For language learning apps generating lesson audio, implement queuing to stay within this limit. Short phrases may take a few seconds to generate, so asynchronous processing is recommended.
- Ensure outbound HTTPS connectivity to port 443
- Adhere to the 60 requests per minute rate limit
- Implement request queuing for high-volume lesson generation
- Account for generation latency (approx. 25 chars/sec for long text)
Authentication Implementation
Authentication ensures that only authorized applications consume your character quota. The API requires a Bearer token in the Authorization header for every request, including voice and model listings. This standard header format allows seamless integration with existing HTTP clients used in language learning platforms.
Header Configuration
Include the header Authorization: Bearer <your-api-key> in every HTTP POST or GET request. The key must be sent exactly as generated; extra whitespace or missing prefixes will result in a 401 Unauthorized response. This applies to both speech synthesis and metadata endpoints.
- Use
Authorization: Bearer tts-...exactly as provided in your dashboard. - Ensure no extra spaces precede the token string.
Bearer Token Security
The API key is the sole credential for your account. Unlike systems with multiple scopes, this key grants full access to your balance and usage data. Keep it out of public version control if your backend exposes it to client-side code, as there is no granular permission set.
- One active key per account; issuing a new one invalidates the old immediately.
- Rotate keys if you suspect exposure, as the old key stops working at once.
Key Management Strategies
Since only one key is active per account, manage rotation carefully to avoid service interruption. Store the key in environment variables rather than hardcoding it. If you suspect a leak, generate a new key from the dashboard; the previous key becomes invalid immediately, securing your balance.
Monitor your usage dashboard regularly. Since there is no rate limit per voice but a global 60 requests per minute limit, ensure your key management does not spawn duplicate sessions that could trigger throttling.
- Generate new keys from the dashboard; old keys stop instantly.
- Store keys in environment variables, not in source code.
Constructing the Request
To generate speech, send a POST request to the TTS endpoint with a JSON body. The payload requires the model (tts-1 or tts-1-hd), the input text (max 4096 characters), and the target voice preset. Optional fields include response_format, speed, and language.
Ensure the input text does not exceed the character limit per request. For longer lessons, split the text into chunks, synthesize each part, and concatenate the resulting audio files to create the final lesson audio.
JSON Body Assembly
Structure the request body with standard JSON fields. Include model, input, voice, response_format, and speed. The API accepts requests in the same format as the OpenAI speech endpoint, allowing you to use existing OpenAI SDKs by adjusting the base URL.
- model: tts-1 or tts-1-hd
- input: text string, max 4096 chars
- voice: one of 8 presets
- response_format: mp3, wav, opus, flac, or pcm
- speed: 0.25–4.0
Voice Parameter Selection
Select a voice preset that matches the educational tone. Female voices include aria, nova, luna, and sage. Male voices include felix, milo, atlas, and orion. Each voice is designed for specific use cases, from narrators to conversational styles.
- aria: warm, clear narrator
- nova: bright, upbeat
- luna: soft, storytelling
- sage: calm, instructional
- felix: energetic, promo
- milo: friendly, conversational
- atlas: neutral, news
- orion: deep, documentary
Language Code Specification
Specify the language parameter using an ISO code to ensure accurate pronunciation. If omitted, the system guesses the language, defaulting to English for Latin-script text. For non-English languages, always set the language code to avoid mispronunciation.
Supported languages include Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, and Turkish.
- Set language for non-English Latin text
- Supported: 23 languages
- Not supported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali and all others not in the list.
- Voice can speak any supported language
Handling the Response
The API returns the synthesized audio as binary data in the response body. Depending on the response_format parameter, this data may be an MP3, WAV, Opus, FLAC, or raw PCM stream. Developers must handle the response stream efficiently to avoid memory issues when processing large audio files.
Save the binary payload directly to a local file or stream it to a player. Ensure the file extension matches the requested format. For example, an MP3 response should be saved with a .mp3 extension. This ensures compatibility with standard audio libraries in your language learning application.
Binary Data Reception
Receive the response body as a byte stream. The content type indicates the format (e.g., audio/mpeg for MP3). Parse the bytes directly into your application’s audio buffer or write them to a temporary file for immediate playback.
Handle network timeouts appropriately, as short phrases may take a few seconds to generate. Ensure your HTTP client supports streaming responses to prevent memory exhaustion during large text synthesis.
- Check Content-Type header to verify format
- Stream bytes to avoid memory loading
- Handle partial responses if network fails
Audio File Saving
Write the received bytes to a file with the correct extension. For instance, if response_format is wav, save the file as .wav. This ensures correct playback by standard media players used in your educational workflow.
Store files temporarily or permanently based on your application’s needs. The generated audio is not stored by the API, so you are responsible for local storage management.
- Match file extension to format (e.g., .mp3)
- Write bytes directly to disk or memory
- Verify file integrity after write
Error State Management
If synthesis fails, the request is free, and the charge is returned in full. Handle HTTP error codes (4xx, 5xx) appropriately. Invalid inputs like exceeding character limits or using unsupported voices will return an error object.
Log error messages to debug issues. Common errors include invalid API keys, rate limits exceeded, or unsupported languages. Implement retry logic for transient network errors, but not for invalid parameters.
Ensure your application handles errors gracefully, providing user feedback in the language learning interface when audio generation fails.
- Failed requests are free
- Log error details for debugging
- Retry on transient network errors
Optimizing for Performance
Efficient synthesis requires managing the queue nature of the API. Requests are processed sequentially, meaning long texts may experience latency during high load. Understanding this processing order helps predict generation times accurately.
Request Queuing Strategy
Since requests are processed one after another, batch smaller phrases into a single 4096-character input where possible to reduce overhead. This minimizes the number of API calls and reduces queuing delays for subsequent requests.
Parallel Request Handling
The 60 requests per minute limit allows for parallel processing if managed correctly. Use multiple worker threads to send independent requests simultaneously, ensuring you do not exceed the per-key rate limit of 60 RPM.
- Monitor the 10 RPM initial limit before top-up.
Cache Implementation Options
Store generated audio files locally for static lesson content to avoid repeated API calls. Generated audio is returned in the response and not stored, so caching the output ensures consistent delivery and reduces character usage for recurring educational material.
Testing the Integration
Verifying the integration ensures the API behaves as expected before committing to production workflows. Start by confirming connectivity and basic synthesis capabilities using standard command-line tools or the official OpenAI SDK with the adjusted base URL.
Curl Verification Steps
Use a simple curl command to send a POST request to https://api.playvebet.com/v1/audio/speech. Include the Authorization header with your Bearer token and a minimal JSON body containing a model, input, and voice parameter. Verify that the response contains binary audio data or a valid error code.
- Set
curl -X POSTwith the correct base URL. - Include
Authorization: Bearer tts-...in headers. - Check for 200 OK status and non-empty audio body.
SDK Validation Methods
Initialize the OpenAI SDK with base_url=https://api.playvebet.com/v1 and your API key. Call the speech method with a short test string. This confirms that your code handles the response format correctly, whether saving to a file or processing in memory.
- Configure SDK client with custom base URL.
- Pass valid
tts-1model and a sample text string. - Verify audio file generation matches expected format.
Edge Case Testing
Test boundary conditions such as the 4096-character limit per request. Verify behavior when sending empty input or invalid voice IDs. Ensure that failed requests return a 200 status with an error object, confirming no charges are applied for invalid inputs.
- Send exactly 4096 characters to test limit.
- Send an empty string to check error handling.
- Verify no charge for failed synthesis requests.
Production Deployment
Deploying the PlayVeBet TTS API requires disciplined monitoring of your 60-requests-per-minute rate limit to ensure consistent delivery for language learners. Since requests are processed sequentially, bursts of simultaneous lesson generation may queue, introducing latency that must be accounted for in your user experience design.
Rate Limit Monitoring
Implement a client-side token bucket or fixed-window counter to track usage against the 60 RPM limit. This prevents 429 Too Many Requests errors during peak lesson playback. The API allows 10 requests per minute for new keys before the first top-up, so monitor initial deployment closely.
- Track usage via the /v1/voices or balance endpoint to predict remaining capacity.
- Implement exponential backoff for retry logic when rate limits are hit.
- Alert on sustained high utilization to prevent queue saturation.
Error Logging Setup
Log request metadata, including timestamp, character count, and status codes, for billing reconciliation and debugging. Failed requests are free, but logging ensures you distinguish between network errors and synthesis failures. Store these logs locally or in a centralized service for audit trails.
- Log all 4xx and 5xx responses with associated voice and model parameters.
- Record character counts to verify billing accuracy against the $0.01 per 1,000 characters rate.
- Capture response times to identify queue-induced delays during high load.
Scaling Considerations
The API processes requests sequentially, meaning under heavy load, generation time increases. For language learning apps, pre-generate audio for static lesson content during off-peak hours to avoid runtime latency. Dynamic content should use parallel requests across multiple keys if available, but note that there is one active key per account.
- Pre-generate long-form lessons to mitigate the ~25 characters per second generation speed.
- Split texts >4096 characters into segments to maintain request size limits.
- Monitor queue depth to adjust user-facing loading states appropriately.

Common Integration Mistakes
Integration failures in language learning platforms often stem from basic configuration errors. Ensuring the correct API base URL and handling character limits prevents silent audio truncation or connection timeouts during lesson playback.
Incorrect Base URL Usage
Use the full base URL https://api.playvebet.com/v1. Omitting the domain or path causes 404 errors.
Missing Language Codes
Set the language field for non-English Latin text. Without it, the system guesses English, causing pronunciation errors in French, German, or Spanish lessons.
Ignoring Character Limits
Limit input text to 4096 characters per request. Exceeding this limit causes the synthesis to fail, returning a 400 error.
Audio Format Selection
Selecting the correct audio format ensures efficient delivery of speech content to learners while maintaining clarity. The API supports MP3, WAV, Opus, FLAC, and PCM, allowing you to optimize for bandwidth, compatibility, or processing needs. Each format serves a distinct role in the educational workflow, from immediate playback to archival storage.
Understanding the trade-offs between file size and computational overhead helps you design scalable language learning applications. By aligning format choice with your delivery infrastructure, you can ensure consistent performance across diverse devices and network conditions without compromising on audio quality.
MP3 vs WAV Trade-offs
MP3 provides lossy compression, significantly reducing file size compared to WAV, which is uncompressed. For language learning apps where storage and bandwidth are critical, MP3 is generally preferred for on-demand playback. WAV offers pristine audio quality but results in larger files, making it suitable for offline caching or high-fidelity recording review.
Choose MP3 for standard lesson playback to conserve mobile data. Use WAV only if your application requires lossless audio for specific pedagogical features, such as precise phoneme analysis, accepting the increased storage cost.
- MP3: Compressed, smaller files, ideal for streaming.
- WAV: Uncompressed, larger files, highest fidelity.
Opus Compression Benefits
Opus delivers superior compression for mobile data conservation, making it highly efficient for users on limited bandwidth. It maintains clarity even at lower bitrates, ensuring that pronunciation nuances remain audible without consuming excessive data.
This format is particularly advantageous for language learning platforms targeting users in regions with varying network reliability. It balances file size and audio clarity effectively, supporting consistent engagement during practice sessions.
- Superior compression for mobile data conservation.
- Maintains clarity at lower bitrates.
PCM Raw Data Usage
PCM provides uncompressed raw audio data, offering zero processing overhead for immediate playback or direct ingestion into audio analysis engines. This format is ideal when your application handles its own compression or requires raw signal data for processing.
Use PCM when integrating with third-party speech recognition tools or custom audio pipelines that manage compression independently. It ensures maximum fidelity without any algorithmic alteration, though it results in the largest file sizes among standard options.
- Uncompressed raw audio data.
- Ideal for custom audio pipelines or immediate playback with zero processing overhead.
Voice Selection Logic
Selecting the correct voice preset ensures educational content matches its pedagogical intent. The API provides eight distinct presets, each with a specific acoustic profile suitable for different language learning contexts. Developers must map these voices to lesson types to maintain auditory consistency.
Matching Tone to Content
Use "aria" for warm, clear narration in introductory modules, while "sage" suits instructional grammar explanations. For conversational practice, "milo" offers a friendly, natural tone. Avoid using "atlas" (neutral news) for interactive dialogues, as its delivery may feel too formal for casual language exercises.
- Aria: Warm narrator for stories
- Sage: Calm instructions
- Milo: Friendly conversation
- Orion: Deep documentary style
Consistency Across Lessons
Maintain the same voice for a specific character or accent throughout a course to aid learner recognition. Since any voice can speak any of the 23 supported languages, you can switch accents while keeping the timbre consistent, aiding in accent discrimination training.
Gender Distribution Options
The API offers four female voices (aria, nova, luna, sage) and four male voices (felix, milo, atlas, orion). This balanced distribution allows for diverse dialogue pairs. Use "nova" for upbeat, bright content and "luna" for softer storytelling to differentiate speakers.
Billing Integration
Integrating billing requires tracking character counts accurately, as every space and punctuation mark consumes credit. The API charges $0.01 per 1,000 characters, with failed requests refunded instantly. Monitor your usage dashboard to align spending with user lesson consumption.
Tracking Character Usage
Calculate input length before each request to predict costs. Since text is limited to 4,096 characters per request, split longer lessons into segments. This ensures precise billing attribution for each language module.
- Count spaces and punctuation as characters
- Split text exceeding 4,096 characters
- Log successful vs. failed requests for accurate balance
Balance Check Implementation
Query the account status regularly to prevent service interruption. The interface displays current balance and remaining characters. Ensure your application handles insufficient funds gracefully by pausing audio generation until top-up.
Top-Up Automation
Use USDT (TRC-20) on the TRON network for deposits. Minimum top-up is $5, credited automatically within minutes. Integrate a listener for blockchain confirmations to update your internal balance without manual refresh.
- Minimum deposit: $5
- Payment: USDT on TRON network
- Credit time: within minutes
Support Channel Utilization
PlayVeBet relies exclusively on email for technical support, maintaining a direct line for integration issues without the distraction of phone lines or live chat agents. This channel ensures that all queries are documented and traceable, which is essential for startups tracking support tickets alongside API usage metrics.
When contacting support, you are interacting with a team that understands the specific constraints of the TTS API, such as character limits and rate limits. Clear communication helps resolve issues faster than general inquiries.
Email Support Best Practices
Include your API key in the subject line or body to allow support to verify your account status and billing history immediately. Mention the specific endpoint and model (tts-1 or tts-1-hd) you are using to narrow down the scope of the investigation.
Attach relevant logs or curl commands that reproduce the issue. Since support is email-only, detailed context in the initial email reduces back-and-forth delays.
- Use the subject line format: '[TTS Issue] - API Key: tts-...'
- Include the exact error message and HTTP status code
- Attach a minimal reproducible code snippet or curl command
Issue Reporting Format
Structure your report with clear sections: Request, Response, and Expected Behavior. Specify the voice, language, and format parameters used in the failing request.
If the issue is related to audio quality or language detection, provide a sample of the input text and the resulting audio file if possible.
- Request details: model, voice, language, format
- Response details: status code, error message, headers
- Expected vs. actual output comparison
Response Time Expectations
Critical billing or key-related issues may receive a faster response.
Note that support does not offer real-time assistance, so plan your development sprints accordingly. For urgent issues during business hours, ensure your email includes 'URGENT' in the subject line.
- Standard response: 24-48 hours
- Billing/key issues: faster response possible
- No live chat or phone support available
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.
Sources and further reading
- Wikipedia
- TRON developer hub: TRC-20
- LibriTTS-R corpus (OpenSLR 141)
- Tether (USDT)
- Python documentation
- LibriTTS-R paper (arXiv 2305.18802)
- LibriVox public-domain audiobooks
- OpenAI API reference: create speech
- W3C WAI: making audio and video accessible
- MDN: Web Speech API
- openai-node on GitHub
- openai-python on GitHub
