Integrate Text-to-Speech API into Your Android App

By VoiceNode editorial team · Updated 2026-11-18

This guide shows you how to add high-quality text-to-speech to your Android app using the VoiceNode API. You will learn to send text requests and receive audio files efficiently, leveraging the familiar OpenAI SDK structure for seamless integration. We cover everything from setting up authentication to handling responses in your preferred format.

Designed for mobile product teams, this page provides concrete steps to generate speech without managing complex infrastructure. You will find specific details on rate limits, error handling, and code examples that help you deliver reliable audio experiences to your users. Let’s get your app speaking in minutes.

Integrate Text-to-Speech API into Your Android App

Frequently asked questions

Do I need the OpenAI SDK?

No. The API accepts standard JSON POST requests, so you can use any HTTP library like OkHttp or Retrofit. You can use any HTTP library like OkHttp or Retrofit, or the official OpenAI SDKs by adjusting the base URL.

Can I use cURL for Android?

cURL is a command-line tool, not a library for Android apps. However, you can use the same JSON request structure shown in cURL examples within your Android code using libraries like OkHttp or Retrofit. The endpoint is POST https://api.playwe1.com/v1/audio/speech.

What happens if I send too much text?

The API limits input to 4096 characters per request. If your text exceeds this, you must split it into smaller parts, synthesize each part, and join the resulting audio files. This ensures reliable processing and avoids request errors due to payload size limits.

Is SSML supported in the API?

No, the API does not support SSML. You send plain text in the input field. If you need pauses or emphasis, you must manage timing and audio concatenation in your app logic after receiving the generated audio files from the synthesis endpoint.

How do I handle streaming audio?

The API does not support streaming or WebSocket connections. It returns the complete audio file in the response body after synthesis finishes. You must wait for the full file to be generated before playing it; short phrases take a few seconds, while longer texts generate at roughly real-time speed.

What is the default language if not set?

If you do not specify a language, the system guesses it from the script. Latin script text defaults to English. For non-English text using Latin characters, you should explicitly set the language parameter to ensure accurate pronunciation and avoid incorrect language detection.

Can I send audio in WAV format?

Yes, you can request audio in WAV format by setting the response_format parameter to "wav". Other supported formats include mp3, opus, flac, and pcm. The API returns the generated audio file in the specified format within the HTTP response body.

How do I rotate my API key?

You can issue a new API key at any time from your account dashboard. The new key becomes active immediately, and the old key stops working at once. This allows you to rotate keys without downtime, ensuring secure access to the TTS service.

Is there a WebSocket endpoint?

No, there is no WebSocket endpoint. The API uses standard HTTP POST requests to send text and receive the resulting audio file. You cannot stream partial audio or maintain a persistent connection; each request is processed independently and returns a complete file.

Do I need to split text manually?

Yes, you must split text manually if it exceeds 4096 characters. The API does not handle splitting automatically. You need to divide your text into chunks, send each chunk to the endpoint, and then join the resulting audio files in your app logic.

What is the speed range?

The speed parameter accepts values between 0.25 and 4.0. This allows you to slow down or speed up the speech synthesis. The speed parameter accepts values between 0.25 and 4.0.

Are responses always JSON?

No. The request body is JSON, but the response contains the audio file itself in the specified format (e.g., mp3, wav). The HTTP response headers indicate the content type. You do not receive a JSON object with audio data; you get the raw audio bytes.

Can I use custom voices?

No, custom voice cloning is not offered. You can choose from eight preset voices: aria, nova, luna, sage, felix, milo, atlas, and orion. Each voice has a distinct tone, but you cannot upload your own voice or design a custom voice for your app.

Is the API compatible with Retrofit?

Yes, the API is compatible with Retrofit. Since it uses standard JSON POST requests similar to the OpenAI speech endpoint, you can easily integrate it into your Android app using Retrofit. Define the endpoint and request body, and handle the audio response in your callbacks.

First request

curl

curl https://api.playwe1.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.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playwe1.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.playwe1.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
ariafemale
novafemale
lunafemale
sagefemale
felixmale
milomale
atlasmale
orionmale
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Authentication

Sound wave illustration for: Authentication

Secure your API access with a Bearer token. Include the header Authorization: Bearer tts-... in every request to the Android TTS endpoint.

Each account maintains only one active key at a time. If you generate a new key, the previous one stops working immediately, ensuring no duplicate usage.

Bearer Token Usage

Bearer Token Usage

Pass your key in the Authorization header as Bearer <your-key>. This standard format works seamlessly with the official OpenAI SDKs by adjusting the base URL.

  • Format: Authorization: Bearer tts-...
  • Include in every API call
  • Works with standard HTTP clients

Single Active Key

Single Active Key

Your account holds exactly one active API key. This simplifies security management for your mobile app's backend or direct client calls.

Key Rotation Policy

You can issue a new key at any time via the dashboard. The old key becomes invalid immediately upon creation of the new one, preventing overlap.

Base URL and Endpoint

Sound wave illustration for: Base URL and Endpoint

To generate audio, send a POST request to https://api.playwe1.com/v1/audio/speech. The API accepts JSON and returns an audio file directly in the response body. This single endpoint handles all synthesis tasks for your Android app.

POST /v1/audio/speech

Send your text payload here. The endpoint processes the input and returns the synthesized audio file in your chosen format.

GET /v1/voices

Use this endpoint to retrieve available voices, supported languages, and formats. It helps you dynamically populate your app’s settings menu with valid options for users.

GET /v1/models

Query this endpoint to confirm the available model versions (tts-1 and tts-1-hd). This ensures your app requests the correct engine configuration.

Request Parameters

Sound wave illustration for: Request Parameters

To generate audio, specify the model as "tts-1" or "tts-1-hd". Both use the same engine and pricing, so choose based on your quality preference. The core payload is the input field, which accepts plain text up to 4,096 characters per request. Longer texts must be split into parts and joined later.

Model Selection

Select "tts-1" for standard generation or "tts-1-hd" for higher fidelity. Both models use the same engine and share identical pricing structures.

Input Text Limits

Each API call accepts a maximum of 4,096 characters. Spaces and punctuation count toward this limit. If your script exceeds this length, split the text into chunks and concatenate the resulting audio files in your app.

Voice and Language Fields

Choose from eight preset voices like "aria" or "atlas". While the system guesses the language from the script, explicitly set the language field for non-English Latin text to ensure accurate pronunciation.

  • Supported: 23 languages including English, Spanish, German, and Japanese
  • Not supported: Vietnamese, Thai, Ukrainian, Romanian, Czech, Bengali

Response Formats

Sound wave illustration for: Response Formats

Choose the audio format that best fits your app’s bandwidth and playback requirements. The API supports five standard formats, allowing you to balance file size against quality and compatibility.

MP3 Output

MP3 is the default and most widely supported format for Android media players. It offers a good balance between file size and audio quality, making it ideal for general use cases where storage efficiency matters.

WAV Output

Select WAV for uncompressed, high-fidelity audio. This format is larger but ensures lossless playback, which is useful for short notifications or alerts where audio clarity is prioritized over data usage.

OPUS, FLAC, PCM Options

OPUS provides excellent compression, while FLAC offers lossless quality. PCM returns raw audio data, suitable for immediate processing or specific hardware interfaces.

Error Handling

Sound wave illustration for: Error Handling

Handling API errors correctly ensures your Android app maintains a smooth user experience even when synthesis fails or quotas are exceeded. By anticipating these responses, you can gracefully update your UI or retry requests without confusing the end user.

429 Rate Limit Errors

Receive a 429 status when exceeding 60 requests per minute (or 10/min before top-up). Implement exponential backoff to retry automatically, as requests queue sequentially under load.

400 Bad Request

Check your JSON payload for invalid characters, missing fields, or unsupported formats. Failed synthesis requests remain free, so verify your input structure before retrying.

500 Server Errors

Indicate temporary server issues. Since metadata is kept for billing, retrying is safe. Support is by email only.

Error Handling

OpenAI SDK Integration

Sound wave illustration for: OpenAI SDK Integration

The API follows the same request shape as OpenAI, allowing you to reuse existing code by simply pointing the SDK to our endpoint. This means you can integrate text-to-speech without rewriting your entire networking layer.

Changing Base URL

Update your SDK configuration to use https://api.playwe1.com/v1 as the base URL. This ensures all requests route through our synthesis engine while maintaining standard compatibility.

Using Official SDK

The official OpenAI SDKs work directly with our API. You only need to adjust the base URL and provide your tts-... Bearer token in the authorization header. No official SDK of our own is provided.

  • Use standard HTTP clients or the OpenAI Python/Node SDKs.
  • Set Authorization: Bearer tts-your-key-here.

JSON Body Structure

Send a JSON payload with model, input, voice, and response_format. The input text must be under 4096 characters. For longer texts, split the input and join the resulting audio files.

  • Model: 'tts-1' or 'tts-1-hd'.
  • Voice: e.g., 'aria', 'nova', 'milo'.
  • Format: 'mp3', 'wav', 'opus', 'flac', or 'pcm'.

Rate Limits

Sound wave illustration for: Rate Limits

Understanding rate limits is crucial for maintaining a smooth audio generation pipeline in your Android app. Our API enforces strict quotas to ensure consistent performance for all users, preventing any single account from monopolizing synthesis resources during peak usage.

60 Requests Per Minute

Once your account is active, you can send up to 60 requests per minute. This limit applies per API key, so ensure you are using your single active key for all your app's background synthesis tasks.

10 Requests Before Top-Up

New accounts start with a lower limit of 10 requests per minute. This allows you to test the integration with your free trial credit without overwhelming the system. Once you top up with USDT, this limit increases to the standard 60 requests per minute.

Queuing Under Load

Requests are processed sequentially. If you send multiple requests rapidly, they may wait in a queue. While typical generation is near real-time, short phrases might take a few seconds. During high load, you might experience slight delays as requests are processed one after another.

Curl Example

Sound wave illustration for: Curl Example

Use this curl command to generate audio directly from your terminal. It demonstrates the standard JSON payload structure required by the VoiceNode API for synthesizing speech.

Simple POST Request

Send a POST request to the speech endpoint with your model, input text, voice selection, and desired output format. The example below synthesizes a short phrase using the Aria voice in MP3 format.

  • Endpoint: https://api.playwe1.com/v1/audio/speech
  • Method: POST
  • Body: JSON with model, input, voice, response_format

Headers Configuration

Include your API key in the Authorization header using the Bearer scheme. Ensure the Content-Type is set to application/json. The key starts with 'tts-' and is unique to your account.

Audio Response Handling

The API returns the audio file directly in the response body. Save this binary output to a file, such as 'speech.mp3', for playback in your Android app. Failed requests return an error JSON instead of audio.

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. Tether (USDT)
  3. W3C WAI: making audio and video accessible
  4. Creative Commons Attribution 4.0
  5. LibriVox public-domain audiobooks
  6. curl documentation
  7. MDN: Web Speech API
  8. openai-node on GitHub
  9. Node.js documentation
  10. OpenAI API reference: create speech
  11. LibriTTS-R corpus (OpenSLR 141)
  12. ISO 639 language codes

More on this site