API Documentation for Text-to-Speech Integration

By VoxApp editorial team · Updated 2026-11-19

This documentation provides the technical specifications for integrating the VoxApp text-to-speech API into Android applications. It details the required endpoints, request parameters, and response formats for generating audio files from text input. The guide covers authentication methods, rate limits, and error handling to ensure reliable integration within mobile environments.

Developers will find concrete examples for SDK initialization, cURL requests, and voice selection. The content focuses on practical implementation steps, including base URL configuration and parameter validation, enabling indie developers to implement high-quality voice features without managing complex infrastructure.

API Documentation for Text-to-Speech Integration

Frequently asked questions

How do I get an API key?

Navigate to /get-api-key/ and sign up using Google or an email and password combination. Upon authentication, the dashboard displays your active API key, current balance, and usage statistics. Each account is associated with a single active key that can be issued anew at any time.

What is the base URL?

The API base URL is https://api.ace65.info/v1. You send POST requests to https://api.ace65.info/v1/audio/speech for synthesis. Other endpoints like /v1/voices and /v1/models are accessible via GET requests against this same base URL structure for retrieving available voices and model details.

Which SDK should I use?

We do not provide an official SDK. You should use the OpenAI SDK or standard HTTP libraries. Configure the SDK by changing the base_url to https://api.ace65.info/v1 and providing your API key. This approach works because our request shape matches the OpenAI speech endpoint specification.

Is the OpenAI SDK compatible?

Yes, the official OpenAI SDKs are compatible. You must change the base_url to https://api.ace65.info/v1 and use your site-specific API key. The request shape for the speech endpoint is identical to OpenAI, allowing seamless integration without modifying the core SDK logic or data structures.

How do I handle errors?

Failed requests are free: if synthesis fails, the charge is returned in full. Monitor the HTTP status code in your response. If an error occurs, the audio file is not generated, and no characters are deducted from your balance. Check the response body for specific error details.

What is the rate limit?

The limit is 60 requests per minute per API key. Before the first top-up, the limit is 10 requests per minute. Requests are processed sequentially, so under load, a request may wait in a queue. Exceeding the limit results in standard rate-limiting errors from the API.

Can I use curl?

Yes, curl is fully supported. The dashboard provides a ready curl example. You send a POST request to the speech endpoint with a JSON body containing the model, input text, voice, and response format. Authentication is handled via the Authorization: Bearer header with your API key.

How do I rotate my key?

You can issue a new API key at any time from your account dashboard. When a new key is issued, the old one stops working immediately. This ensures that only one active key exists per account at any given time, simplifying access management and security protocols.

What models are available?

Two models are available: tts-1 and tts-1-hd. Both use the same engine and have identical pricing. Select the model in your request body. The choice does not affect the cost or the character limits per request.

Do I need to install a library?

No, you do not need to install a proprietary library. You can use standard HTTP clients or the OpenAI SDK. Since we do not offer a mobile SDK, standard RESTful HTTP requests are sufficient for integration into any Android application or backend service.

Is there a mobile SDK?

No, there is no official mobile SDK. You should use standard HTTP libraries or the OpenAI SDK configured with our base URL. This allows you to integrate the TTS functionality directly into your Android application using native networking capabilities without relying on a specific vendor-provided mobile package.

How do I parse the response?

The response contains the generated audio file directly. The format depends on your requested response_format (mp3, wav, opus, flac, or pcm). Save the binary response data to a file or stream it directly in your application.

What happens on timeout?

If a request times out or fails, the charge is returned in full. No characters are deducted from your balance. The audio file is not generated. You should retry the request if appropriate, keeping in mind that requests are processed sequentially and may wait in a queue under load.

Is the API RESTful?

Yes, the API is RESTful. It uses standard HTTP methods: POST for speech synthesis and GET for retrieving voices and models. Requests are sent as JSON, and responses contain audio data. This structure allows easy integration with standard web and mobile development tools.

First request

curl

curl https://api.ace65.info/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.ace65.info/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.ace65.info/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

Authentication for the VoxApp TTS API requires a Bearer token passed in the Authorization header. Each account is provisioned with a single active API key, which must be included in every request to verify identity and track usage against your balance.

Bearer Token Format

Bearer Token Format

Include the header Authorization: Bearer tts-... with every API call. The token string begins with the prefix tts- followed by unique alphanumeric characters assigned to your account. Ensure no extra whitespace surrounds the token value to avoid authentication failures.

API Key Generation

API Key Generation

Your API key is available immediately after signing up on the /get-api-key/ page. Accounts created via Google login receive a $0.50 trial credit, while email-based accounts start without credit. The key is displayed in the dashboard alongside your current balance and usage statistics.

Key Rotation Policy

A new key can be issued at any time via the dashboard. When a new key is generated, the previous key becomes invalid immediately. This ensures that if a key is compromised, access can be revoked instantly without waiting for a cooldown period.

Endpoint Specification

Sound wave illustration for: Endpoint Specification

The API exposes three primary endpoints for speech synthesis and metadata retrieval. The speech endpoint accepts text and configuration parameters to generate audio files. The voices and models endpoints provide static metadata about available synthesis options and pricing tiers.

Speech Generation Endpoint

Send a POST request to https://api.ace65.info/v1/audio/speech. The JSON body requires model, input, and voice fields. Supported response formats include mp3, wav, opus, flac, and pcm.

Voices List Endpoint

Access GET /v1/voices to retrieve the full list of eight voice presets, supported languages, and available audio formats. This endpoint confirms the eight available presets and their characteristics.

Models List Endpoint

Query GET /v1/models to identify available synthesis engines. Both tts-1 and tts-1-hd map to the same engine with identical pricing.

Request Parameters

Sound wave illustration for: Request Parameters

Configure the core parameters for each synthesis request to define audio quality, content constraints, and voice identity. The API requires precise alignment between the selected model, the input text length, and the desired voice preset to ensure valid processing and optimal output.

Model Selection

Specify either "tts-1" or "tts-1-hd" in the model field. Both options utilize the same underlying engine and pricing tier, allowing you to select the configuration that best fits your latency requirements without affecting the per-character cost.

Input Text Field

The input parameter accepts plain text strings with a maximum length of 4096 characters. Spaces, punctuation, and special characters are counted toward this limit. For texts exceeding this threshold, split the content into chunks and join the resulting audio files sequentially.

Voice Preset Selection

Select one of eight presets: aria, nova, luna, sage, felix, milo, atlas, or orion. Each voice supports all 23 available languages. If the language field is omitted, the system guesses the language based on the script, defaulting to English for Latin text.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion
  • Supports 23 languages including English, German, Japanese, and Arabic

Response Formats

Sound wave illustration for: Response Formats

The API returns synthesized audio as a binary payload within the HTTP response body. The client must parse the raw bytes and write them to a file or stream. The format is determined by the response_format parameter in the request, allowing developers to choose between lossy and lossless compression based on their application's storage and bandwidth constraints.

MP3 Audio Output

MP3 is the default format and provides efficient compression suitable for most mobile applications. It balances file size with acceptable audio quality, making it ideal for caching on Android devices. This format is recommended for general-purpose voice features where storage efficiency is a priority.

  • Default output format
  • Supports standard MP3 decoding on all Android versions
  • Optimal for reducing bandwidth usage

WAV Audio Output

WAV delivers uncompressed PCM audio. This format is suitable for applications requiring precise audio editing or high-quality playback without decoding artifacts. Note that WAV files are significantly larger than MP3s, which may impact storage costs and load times on mobile devices.

  • Uncompressed 16-bit PCM audio
  • Ideal for archiving
  • Larger file size compared to compressed formats

Opus and FLAC Options

Opus offers high-quality audio at lower bitrates than MP3, making it efficient for variable network conditions. FLAC provides lossless compression, reducing file size while preserving all audio data. Both formats are valid choices depending on whether the priority is bandwidth efficiency or perfect audio fidelity.

  • Opus: High quality at low bitrates
  • FLAC: Lossless compression
  • Both require modern Android audio libraries for playback

SDK Integration

Sound wave illustration for: SDK Integration

The API mirrors the OpenAI speech endpoint structure, allowing direct use of official OpenAI SDKs with minimal configuration. This compatibility simplifies integration for developers already familiar with standard TTS workflows, requiring only a base URL adjustment and the correct authentication header.

By pointing the SDK to the API base URL, developers can leverage existing client libraries for reliable request handling. This approach eliminates the need for a proprietary SDK while maintaining full access to all voice presets and audio formats.

OpenAI SDK Compatibility

The request shape matches the OpenAI speech endpoint exactly. Developers can use the official OpenAI Python or JavaScript SDKs without modifying the core logic, only adjusting the endpoint configuration.

Base URL Configuration

Set the base URL to https://api.ace65.info/v1. This directs all SDK requests to the VoxApp infrastructure while maintaining standard OpenAI-compatible parameters for model, voice, and input text.

Client Initialization

Initialize the client with your Bearer token. The SDK handles JSON serialization and response parsing automatically. Ensure the token is passed in the Authorization header as 'Bearer tts-...'.

This setup enables integration into Android app backends or local development environments.

  • Use standard OpenAI SDK clients
SDK Integration

Error Handling

Sound wave illustration for: Error Handling

The API returns standard HTTP status codes to indicate request outcomes. A 200 OK confirms successful synthesis, while a 400 Bad Request indicates invalid parameters such as exceeding the 4096-character limit or using an unsupported voice. A 500 Internal Server Error signals a transient backend issue, which is resolved by retrying the request.

Common Error Codes

Beyond standard codes, the system uses specific error types for business logic. A 429 Too Many Requests indicates you have exceeded your rate limit. A 402 Payment Required appears when your balance is insufficient for the requested characters. Ensure your input text is properly encoded to avoid 400 errors.

  • 400: Invalid request body or parameters
  • 402: Insufficient balance
  • 429: Rate limit exceeded
  • 500: Internal server error

Rate Limit Errors

  • 10 req/min (pre-topup)
  • 60 req/min (post-topup)

Authentication Errors

A 401 Unauthorized error occurs if the Bearer token is missing or malformed. Ensure the header is formatted as Authorization: Bearer tts-.... If the key was revoked via the dashboard, it becomes inactive immediately, also resulting in a 401 error. Generate a new key from the /get-api-key/ page.

Rate Limits

Sound wave illustration for: Rate Limits

The API enforces a hard limit of 60 requests per minute per active key. Requests are processed sequentially, so under heavy load, synthesis may queue behind previous jobs. Each request handles up to 4,096 characters of input text.

Requests Per Minute

Each API key allows a maximum of 60 requests per minute. If you exceed this threshold, subsequent requests will receive a 429 Too Many Requests error until the window resets.

Pre-Topup Limit

New accounts with the free trial credit ($0.50) are restricted to 10 requests per minute. This lower limit ensures fair usage during the trial period while allowing indie developers to validate integration without consuming the full 60-request capacity.

Post-Topup Limit

Once you top up your balance via USDT (TRC-20), the rate limit increases to the standard 60 requests per minute. Top-ups are processed automatically within minutes.

Curl Example

Sound wave illustration for: Curl Example

To generate audio, send a POST request to the speech endpoint with your bearer token and model parameters. The API returns the audio file directly in the response body, allowing immediate playback or storage in your Android application.

Basic Request Structure

Construct a JSON payload containing the model, input, voice, and response_format fields. The maximum input length is 4,096 characters. For longer texts, split the content into chunks and concatenate the resulting audio files.

Headers Configuration

Include the Authorization header with your API key in the format Bearer tts-.... Ensure the Content-Type is set to application/json. The request must be sent to https://api.ace65.info/v1/audio/speech.

Response Parsing

The API returns the audio file directly. Use your HTTP client to handle the binary response data. Save the output to a file or pass it directly to your media player for immediate playback in the application.

Listen to the 8 voices

Each sample below was generated by this API from the same sentence. Understanding these distinctions helps developers select the right tool for their app’s audio needs without over-engineering the solution.

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. MDN: Web Speech API
  3. ISO 639 language codes
  4. LibriVox public-domain audiobooks
  5. Node.js documentation
  6. Python documentation
  7. TRON developer hub: TRC-20
  8. LibriTTS-R corpus (OpenSLR 141)
  9. Creative Commons Attribution 4.0
  10. curl documentation
  11. openai-python on GitHub
  12. IETF RFC 7845: Ogg Opus

More on this site