Custom API Setup Guide - Voice Reader

🔧 When to Use Custom API

Use Custom API when you want to connect to:

Self-hosted TTS servers (OpenAI-compatible APIs)
Third-party TTS services not built into Voice Reader
Enterprise TTS endpoints with custom authentication

API Specification

Your TTS endpoint must accept HTTP POST requests and return audio data. Voice Reader supports two request formats:

Option 1: JSON Request Body

Request
POST /api/tts
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "text": "Hello, world!",
  "voice": "en-US-JennyNeural",
  "rate": 1.0
}

Option 2: SSML Request Body

Request
POST /api/tts
Content-Type: application/ssml+xml
Authorization: Bearer YOUR_API_KEY

<speak version="1.0" xml:lang="en-US">
  <voice name="en-US-JennyNeural">
    <prosody rate="1.0">Hello, world!</prosody>
  </voice>
</speak>

Response Format

Your API must return audio data directly in the response body:

Response
HTTP/1.1 200 OK
Content-Type: audio/mpeg

[Binary audio data...]

Supported Audio Formats

Format	Content-Type	Notes
MP3	`audio/mpeg`	Recommended, best compatibility
WAV	`audio/wav`	Larger file size
OGG	`audio/ogg`	Good compression
AAC	`audio/aac`	iOS native format

Request Parameters

Voice Reader sends these parameters in the JSON request body:

Parameter	Type	Description
`text`	string	The text to synthesize (required)
`voice`	string	Voice ID from your settings
`rate`	number	Speech rate (0.5 - 2.0, default 1.0)

Configure in Voice Reader

Open Voice Reader Settings and configure:

Provider: Custom API
API URL: Your endpoint URL (e.g., https://api.example.com/tts)
API Key: Your authentication token (sent as Bearer token)
Voice ID: The voice identifier your API expects

⚠️ Security Note

Your API key is stored securely on your device and is only sent to the URL you configure. Never share your API key with others.

Example: OpenAI-Compatible Server

Many self-hosted TTS solutions provide OpenAI-compatible APIs. Here's an example configuration:

Settings
Provider: Custom API
API URL: http://localhost:8080/v1/audio/speech
API Key: (leave empty for local)
Voice ID: alloy

Troubleshooting

No audio playing

Verify your API URL is accessible from your device
Check that your API returns valid audio data
Ensure the Content-Type header matches the audio format

Authentication errors

Verify your API key is correct
Check if your API uses a different auth method
Some APIs require the key in a custom header

Network errors

For local servers, ensure your device is on the same network
Check if your server allows CORS (for web-based APIs)
Verify the server is running and accepting connections

💡 Need Help?

If you're having trouble setting up a custom API, contact us with details about your TTS service and we'll help you configure it.