How to Integrate TTS API in Android Apps?

By VoiceNode editorial team · Updated 2026-11-18

This guide walks Android product teams through integrating the VoiceNode TTS API into their apps. We cover the full workflow from account setup to playing synthetic audio, using concrete code examples that match our API’s structure. You’ll learn how to handle audio files efficiently without managing complex infrastructure.

The instructions focus on reliable, character-based generation suitable for mobile contexts. We explain how to configure the OpenAI-compatible SDK, manage rate limits, and handle long texts by splitting and concatenating audio segments. By the end, you’ll have a clear path to adding voice features to your Android application.

How to Integrate TTS API in Android Apps?

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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Performance Optimization

Language Support

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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

Sound wave illustration for: 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.

Avatar of the voice aria
ariafemale
Avatar of the voice nova
novafemale
Avatar of the voice luna
lunafemale
Avatar of the voice sage
sagefemale
Avatar of the voice felix
felixmale
Avatar of the voice milo
milomale
Avatar of the voice atlas
atlasmale
Avatar of the voice orion
orionmale

23 languages

Any voice speaks any of these languages.

Sources and further reading

  1. Wikipedia
  2. openai-python on GitHub
  3. openai-node on GitHub
  4. ISO 639 language codes
  5. Tether (USDT)
  6. IETF RFC 7845: Ogg Opus
  7. Node.js documentation
  8. MDN: Web Speech API
  9. Creative Commons Attribution 4.0
  10. Python documentation
  11. W3C WAI: making audio and video accessible
  12. TRON developer hub: TRC-20

More on this site