Frequently asked questions
What SDK should I use for Android?
Use the official OpenAI SDK or plain HTTP requests. Configure the base URL to https://api.playwe1.com/v1 and provide your Bearer token. We do not offer a dedicated mobile SDK, so standard HTTP libraries like OkHttp work perfectly for integrating our text-to-speech API into your Android application.
Can I play audio directly from the API response?
Yes, the API returns the audio file directly in the response body. You can pipe this data straight to your Android audio player without saving it to storage first. This approach reduces memory overhead and simplifies your code by handling the audio data as a direct output of the synthesis request.
How do I handle large texts in Android?
Split your input text into chunks of up to 4096 characters. Send each chunk as a separate request and join the resulting audio files on the client side. This ensures you stay within the character limit per request while delivering seamless audio playback for longer content in your mobile app.
Is the API synchronous or asynchronous?
The API returns the audio file once synthesis completes. Requests are processed sequentially, so under load, a request may wait in a queue. Use asynchronous calls in your Android app to prevent blocking the UI thread while waiting for the response to return.
Do I need to download models?
No, you do not need to download or manage any models. The synthesis engine runs on our cloud servers. Your Android app simply sends text via HTTP and receives the generated audio file. This keeps your app size small and ensures you always use the latest engine version.
How do I set the language in Android?
Pass the optional language field with an ISO code in your JSON body. If omitted, the system guesses the language from the script, defaulting to English for Latin text. Explicitly setting the language ensures accurate synthesis for non-English Latin-script texts.
Can I use this with Kotlin Coroutines?
Yes, integrate seamlessly using Kotlin Coroutines. Make the API call within a suspend function using a coroutine scope. This allows you to handle the asynchronous HTTP request efficiently without blocking the main thread, ensuring a smooth user experience while the text-to-speech synthesis occurs on our servers.
What is the maximum text length?
The maximum input text length is 4096 characters per request. Spaces and punctuation count toward this limit. If your text exceeds this, split it into smaller parts, generate audio for each, and concatenate the results in your Android app to deliver the complete audio output to the user.
How do I handle network failures?
Implement retry logic for failed requests. Failed synthesis requests are free, so retrying does not incur extra costs. Ensure your Android app handles HTTP errors gracefully, retrying the request after a short delay if the network is unstable or if the server is temporarily busy processing other requests.
Is caching audio files recommended?
Caching is optional but can improve performance for repeated content. Since we do not store generated audio, you must manage caching locally in your Android app. Cache files based on the text and voice parameters to avoid redundant API calls, saving time and keeping your usage costs predictable.
Do I need to handle audio decoding?
No, you do not need to handle decoding if you choose standard formats like MP3 or WAV. Our API returns the audio file directly. For formats like FLAC or OPUS, ensure your Android app supports decoding these codecs, or convert them if necessary for your specific playback requirements.
Can I use this for accessibility features?
Yes, the API is ideal for accessibility features like screen readers. Generate audio from text dynamically to provide auditory feedback for visually impaired users. Use voices like Sage for calm instructions or Aria for clear narration.
How do I track usage in Android?
Track usage by monitoring your API key's balance and character count. The API dashboard shows characters used and remaining balance. Log the character count of each request in your Android app to estimate costs, as pricing is $0.01 per 1,000 characters, including spaces and punctuation.
Is there a demo app available?
We do not provide a dedicated demo app. You can test the API directly using the ready curl example on the /get-api-key/ page or by using the OpenAI SDK with our base URL. This allows you to quickly verify integration in your Android environment without downloading additional software.
Preparation
Getting started with VoiceNode in your Android project requires minimal setup. You only need a Google account or email to create an account, then grab your API key from the dashboard. No complex infrastructure management is needed on your end.
Once registered, you can immediately see your key, balance, and usage stats. The API follows standard OpenAI request shapes, meaning you can use existing HTTP libraries or the OpenAI SDK with a simple base URL change. This keeps your integration lightweight and familiar for mobile teams.
Create an Account
Visit the /get-api-key/ page and sign up using Google or an email address. Accounts are specific to this site, so ensure you are on playwe1.com. Google sign-ups include a $0.50 trial credit valid for 7 days, while email accounts start with zero balance.
Get API Key
After logging in, navigate to the dashboard to find your active API key. It starts with "tts-" and is used for authentication. You can issue a new key at any time, which instantly invalidates the old one, ensuring secure access for your app.
Install Dependencies
You do not need a proprietary SDK. Use any standard HTTP client like OkHttp or the official OpenAI Java/Kotlin SDK. Configure the base URL to https://api.playwe1.com/v1. No additional plugins or browser extensions are required for this backend integration.
SDK Configuration
Configuring the SDK is the first step to connecting your Android app to the VoiceNode synthesis engine. You need to point the client to our specific API base URL so all requests route correctly without hardcoding endpoints later.
Set Base URL
Initialize your TTS client by setting the base URL to https://api.playwe1.com/v1. This ensures that all subsequent calls, such as requesting voices or generating speech, use the correct domain for our network.
Initialize Client
Create an instance of the client using the official OpenAI SDK or a standard HTTP library. Since our request shape matches the OpenAI standard, you can use the same initialization patterns you are already familiar with, just adjusting the endpoint.
Add Security Headers
Attach your API key to every request using the Authorization: Bearer header. Pass your unique key generated from the /get-api-key/ page. This authenticates your account and allows us to track your character usage against your balance.
- Key format:
Bearer tts-... - One active key per account
Making the Request
To generate audio, send a POST request to the speech endpoint with a JSON body containing your input text, chosen voice, and desired output format. The API accepts standard formats like mp3 or wav, allowing seamless integration into Android media players.
You can also adjust the playback speed between 0.25x and 4.0x or specify an ISO language code to ensure accurate synthesis, especially for non-English Latin text. The model parameter accepts either "tts-1" or "tts-1-hd" for identical pricing and quality.
Prepare JSON Body
Construct a JSON object with the required fields: model, input, voice, and response_format. Ensure your text does not exceed 4,096 characters, as longer inputs will result in an error. You may optionally include speed and language to refine the output.
The voice field accepts one of eight presets, such as 'aria' for narration or 'felix' for energetic promos. Each voice supports all 23 languages, so you do not need separate models for different tongues.
model: "tts-1" or "tts-1-hd"input: your text string (max 4096 chars)voice: e.g., "aria", "nova"response_format: "mp3", "wav", "opus", "flac", or "pcm"
Send POST Request
Use your preferred HTTP library to send the request to https://api.playwe1.com/v1/audio/speech. Include your API key in the Authorization header as a Bearer token. The request must be sent over HTTPS to ensure secure transmission of your data.
The API processes requests sequentially, so under load, you may experience slight delays. However, short phrases typically return within seconds, making the API suitable for interactive app features like button clicks or read-aloud functions.
- Endpoint:
POST /v1/audio/speech - Header:
Authorization: Bearer <your-key> - Content-Type:
application/json
Handle Response
On success, the API returns the audio file directly in the response body. You can save this binary data to local storage or pass it directly to a media player like ExoPlayer for immediate playback. Failed requests return a JSON error object with details on what went wrong.
Remember that failed requests are free, so you can safely retry without worrying about consuming your character balance. Always check the HTTP status code to distinguish between successful audio generation and client or server errors.
- Success: Returns raw audio bytes
- Error: Returns JSON error details
- Retry logic recommended for network issues
Playing Audio
Once your API returns audio data, you need to render it for the user. VoiceNode supports multiple formats like MP3 and WAV, ensuring compatibility with standard Android media players. You can save the file locally for offline playback or stream it directly for immediate listening.
Efficient audio handling keeps your app responsive. Choose the method that best fits your user experience, whether it’s a quick notification sound or a longer voice-over.
Save Audio File
Write the returned binary data to a temporary file in your app’s cache directory. This allows users to listen to the same phrase again without re-downloading it. Remember to clean up old files to save device storage.
Use the response_format parameter in your request to specify MP3 for smaller file sizes or WAV for higher quality if needed.
- Save to
ContextCompat.getCacheDir() - Delete files older than 24 hours
- Use MP3 for efficient storage
Use ExoPlayer
ExoPlayer is the recommended media player for Android. It handles various audio formats smoothly and supports background playback. Initialize it with the URI of your saved file or a direct stream URL.
It manages audio focus automatically, pausing music when your TTS plays and resuming afterward. This prevents audio conflicts with other apps.
- Handle audio focus changes
- Support background playback
- Smooth format switching
Stream Response
For instant playback, pipe the API response directly into ExoPlayer’s DataSource. This avoids writing to disk, reducing latency and storage usage. Ideal for short phrases or real-time interactions.
Ensure your network thread handles the stream efficiently to prevent UI jank.
- Pipe stream to ExoPlayer
- Reduce latency
- Save device storage
Error Management
Android apps face unique network conditions, from spotty Wi-Fi to aggressive battery savers. Proper error handling ensures your users hear the audio without jarring interruptions or silent failures.
By anticipating common issues like timeouts or rate limits, you can keep the audio playback smooth and maintain a good user experience even when the API is under load.
Catch Timeouts
Set reasonable timeout values for your HTTP client. If the API takes too long, fail fast rather than hanging the UI thread. Short phrases might take a few seconds, so avoid setting timeouts under 10 seconds.
- Use a 15-second read timeout
- Cancel pending requests if the user navigates away
- Log timeout events for debugging
Handle Rate Limits
The API allows 60 requests per minute per key. If you exceed this, you will receive a 429 status code. Respect the retry-after header to avoid being temporarily blocked.
- Monitor your usage dashboard
- Implement exponential backoff
- Queue requests during high load
Retry Logic
Implement a retry mechanism for transient errors. Only retry idempotent requests. Do not retry failed text synthesis if the input was invalid, as that will just waste credits.
- Retry up to 3 times
- Use exponential backoff
- Avoid retrying 4xx errors
Long Text Handling
Long texts exceed the 4,000-character limit per request. Split your input into smaller chunks and synthesize them sequentially. Join the resulting audio files to create a continuous track.
Split Input Text
Divide your input into segments of up to 4,096 characters. Each segment triggers a separate API call. This ensures compliance with the request limit while maintaining text integrity.
- Max 4,096 characters per request
- Spaces and punctuation count
- Sequential processing required
Concatenate Audio
Receive audio files for each chunk. Concatenate them in order to play a seamless audio file. The API processes requests one after another, so longer texts may take time.
Manage Memory
Store temporary audio files in the device’s cache. Delete them after playback to free up storage. This prevents memory leaks during large text synthesis.
Performance Optimization
TTS generation is not instant; short phrases take a few seconds, and requests process sequentially. To keep your Android UI responsive, offload synthesis to background threads like Coroutines or Executors. This prevents the main thread from freezing while waiting for the API response.
Cache Short Phrases
Store frequently used audio files locally. Since generated audio is not stored by the API, caching on the device reduces redundant API calls and saves your character balance.
Background Threads
Use async tasks for API requests. This ensures your app remains interactive while the synthesis engine processes your text, which typically takes about 25 characters of text per second of generation.
Network Efficiency
Minimize payload size by sending only necessary text. Avoid sending large blocks of text in a single request if possible, as this can lead to longer processing times and potential timeouts under load.

Language Support
Language support is broad but finite. Our API handles 23 languages, from Arabic to Turkish, with any voice capable of speaking any supported language. This flexibility simplifies localization for global mobile apps without needing multiple voice models.
You can explicitly set the language using an ISO code in the request body. This ensures consistent output regardless of the input text's script, preventing accidental misidentification of similar languages like Spanish and Portuguese.
Set Language Code
Always provide the language field in your JSON body for non-English texts using Latin script. This overrides automatic detection and guarantees the correct pronunciation rules are applied. For example, setting language: "de" ensures German phonetics even if the text looks similar to Dutch.
- Supported: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
- Unsupported: Vietnamese, Indonesian, Thai, Ukrainian, Romanian, Czech, Bengali, and others.
Auto-Detection Limits
If you omit the language field, the API guesses the language based on the character script. This works well for English but may fail for mixed-language text or less common scripts. Explicitly setting the code is safer for production apps.
Latin Script Default
Without an explicit language code, Latin script text defaults to English. If your app generates French or Dutch text, you must specify the language. Otherwise, the engine will read it with an English accent, which may degrade user experience.
Testing
Before integrating into your production Android app, verify the API works correctly using the free trial credit. This allows you to test the full synthesis workflow without any financial risk, ensuring your integration logic handles responses and errors as expected.
Use Free Trial
Sign in with Google to receive $0.50 of trial credit, which covers approximately 50,000 characters. This is sufficient to test the available voices and formats. The trial is valid for 7 days, giving you ample time to validate your Android implementation.
Check Character Count
Ensure your input text does not exceed 4,096 characters per request. Remember that spaces and punctuation count toward this limit. If your text is longer, split it into parts and concatenate the audio files as described in the long text handling guide.
Verify Audio Output
Download the generated audio file and play it back to confirm clarity and speed. Check that the response_format matches your requirements (mp3, wav, opus, flac, or pcm). Verify that the voice sounds natural and the speed setting (0.25–4.0) meets your app’s needs.
Production Deployment
Once your Android app is live, keeping track of character consumption ensures you avoid unexpected service interruptions. The dashboard on /get-api-key/ provides a clear view of your current balance and usage history, allowing you to anticipate when credits will run low.
Monitor Usage
Regularly check your account page to see exactly how many characters have been processed. Since charges are based on character count including spaces, accurate monitoring helps you stay within budget without over-provisioning.
Top Up Balance
When your balance is low, add funds using USDT on the TRON network (TRC-20). Minimum top-ups are $5, and credits are typically available within minutes after the transfer is confirmed, ensuring your app continues generating audio without delay.
- Supports USDT on TRON (TRC-20) only.
- Minimum top-up amount is $5.
- Credits are credited automatically within minutes.
Rotate Keys
You can issue a new API key at any time from your account page. The old key stops working immediately, which is useful for security or if you suspect a key has been exposed in your app’s build configuration.
- Issue a new key anytime.
- Old key stops working immediately.
Common Issues
Integration rarely goes perfectly smooth on the first try. These three errors account for most initial friction when connecting your Android app to the VoiceNode API.
Invalid Token
If you receive a 401 error, your API key is either missing, expired, or incorrect. Remember that each account has only one active key; issuing a new one instantly invalidates the old one, so ensure your app uses the current credential.
- Check the Authorization header format: 'Bearer tts-...'
- Regenerate key if lost; old key stops immediately.
Model Not Found
Ensure you are sending 'tts-1' or 'tts-1-hd' as the model name. Using an outdated or incorrect model string will cause the synthesis to fail instantly.
Input Too Long
The API accepts up to 4096 characters per request. If your text exceeds this limit, split it manually into chunks before sending, then concatenate the resulting audio files.
Best Practices
Following these guidelines ensures your Android app delivers reliable audio without unnecessary delays or API errors. By respecting character limits and handling network conditions properly, you maintain a smooth user experience even under heavy load.
Use HTTPS
Always use HTTPS for all API calls to ensure your API key remains secure during transmission. Since VoiceNode requires a Bearer token in the Authorization header, protecting this credential is essential to prevent unauthorized usage of your balance.
Limit Request Size
Keep each request under 4,096 characters to avoid truncation or errors. If your text exceeds this limit, split it into smaller chunks before sending. This approach aligns with our single-request constraint and helps manage memory usage on mobile devices.
Handle Errors Gracefully
Implement robust error handling for common issues like rate limits or network timeouts. Since requests are processed sequentially, brief delays may occur during peak times. Inform users politely if synthesis takes slightly longer than usual, rather than showing a generic error.
- Check for 429 status codes to detect rate limits (60 requests/minute).
- Implement exponential backoff for transient network errors.
- Validate character count before sending to avoid input errors.
Listen to the 8 voices
Each sample below was generated by this API from the same sentence. For short phrases, generation may take a few seconds due to initialization overhead.
23 languages
Any voice speaks any of these languages.
