Text to Speech API Integration: Developer's Complete Guide

TL;DR: DubVoice.ai TTS API is REST-based, sk_ key auth, supports webhooks. POST text + voice_id to /api/v1/tts; poll GET /api/v1/tts/{task_id} for audio_url + srt_url. Free tier credits included with every account.

Looking to add text-to-speech capabilities to your application? This developer guide covers everything you need to integrate the DubVoice.ai TTS API — from authentication to production best practices.

Why Use a TTS API?

Building text-to-speech from scratch requires massive datasets, expensive GPU infrastructure, and deep ML expertise. A TTS API gives you:

• Production-ready voices — 17,800+ natural voices out of the box
• Multi-language support — 50+ languages with one API
• Scalability — Handle thousands of requests without infrastructure concerns
• Continuous improvement — Voice quality improves without any work on your end

Quick Start

Authentication

All API requests require an API key. Get yours from the DubVoice.ai dashboard under Settings > API Keys.

Basic Request

curl -X POST https://dubvoice.ai/api/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to our application!",
    "voice_id": "voice_rachel",
    "language": "en"
  }'

Response

The API returns an audio file (MP3 by default) along with metadata including character count and processing time.

Integration Patterns

Pattern 1: On-Demand Generation

Generate audio when the user requests it. Best for interactive applications, chatbots, and accessibility features.

Pattern 2: Pre-Generation

Generate and cache audio for known content. Best for e-learning platforms, IVR systems, and static content.

Pattern 3: Streaming

For real-time applications where low latency matters. Generate and stream audio chunks as they're produced.

Best Practices

• Cache aggressively — If the same text is requested multiple times, serve from cache
• Handle rate limits — Implement exponential backoff for 429 responses
• Validate input — Check text length and content before sending to the API
• Monitor usage — Track character consumption to avoid unexpected costs
• Use webhooks — For long-form content, use async generation with callbacks

Error Handling

Always implement proper error handling:

• 400 — Invalid request (check text length, voice ID, language)
• 401 — Invalid or expired API key
• 429 — Rate limit exceeded (implement backoff)
• 500 — Server error (retry with exponential backoff)

Pricing for API Usage

API usage consumes credits from your DubVoice.ai balance at the same rate as the web interface. One credit equals one character. Packages range from 250K credits ($4.99) to 40M credits ($110).

Common Use Cases

• Mobile apps — Add voice narration to reading apps, news apps, or navigation
• Web applications — Accessibility features, audio content, user notifications
• IoT devices — Smart home announcements, embedded voice responses
• Games — NPC dialogue, narrator voice, dynamic story content
• SaaS platforms — Audio versions of reports, dashboards, and alerts

Synchronous or asynchronous — pick before you build

Whether you await the render or submit and poll is the decision that shapes the rest of the integration, and it is easy to get wrong by defaulting.

Short text returns fast enough to await inline. A greeting, a notification, a product name — a second or two, and blocking is simpler than the alternative. Long text does not. A 15,000-character article can take minutes, and a serverless function that sits waiting on it will be killed by the platform long before the audio is ready.

The failure mode is specific and worth naming: your function times out, your user sees an error, and the job finishes successfully on the server anyway. You have burned the credits and lost the result.

So above a few thousand characters, submit and poll. Take the task id back immediately, return it to the browser, and let the browser poll a thin status route. The request that submits stays under a second no matter how long the render takes.

Handling failures without charging twice

Two rules cover most of what goes wrong.

Treat a rate limit as a wait, not an error. A 429 carries a Retry-After header telling you how long to hold off. Honour it rather than retrying immediately — retrying into a rate limit just extends it. Back off exponentially with a little randomness so concurrent workers do not all retry in lockstep.

Make retries idempotent. If your job runner crashes after submitting but before recording the task id, the naive fix is to submit again — and now you have paid twice for one piece of audio. Write the task id to your database before you do anything else with it, and check for an existing one before submitting.

What to store, and for how long

Store the task id, the text hash, the voice id and the resulting audio URL. The text hash is what lets you skip a render entirely when the same script comes through again, which in practice is often — the same product description gets requested repeatedly.

Do not treat the provider's URL as permanent storage. Download the file and put it somewhere you control, on your own schedule. A URL you did not issue can expire, and the first you will hear of it is a support ticket about a dead player.

For the wider tour of what else is available over the same key, see [everything the platform can do](/blog/everything-you-can-do-with-dubvoice-ai).

Getting Started

• Sign up at dubvoice.ai and get your API key
• Test with a simple cURL request
• Integrate into your application using your preferred language
• Test across different voices and languages
• Deploy and monitor usage

Check our full API documentation at dubvoice.ai/api-docs for complete endpoint reference, voice catalog, and language codes.