Text-to-Speech API Guide: Add Voiceover to Your Product
How to integrate text to speech into your own app with a VoiceSmiths API key: create a key, call generation, receive audio plus character timestamps, credit billing with auto-refund, and error handling.
VoiceSmiths TeamListen to this article
AI narration · about 2 minThe studio is for humans; bulk generation inside a product goes through the API. This guide follows the integration order.
1. Create an API key
Sign in and open API keys. Create one — it's shown once, so store it safely; revoke and recreate from the same page if it leaks.
2. Generate speech
Submit text, a voice ID and a model; you get back an audio URL plus character-level timestamps (start/end seconds per character), so subtitles need no post-processing. The body mirrors the studio: text, voiceId, modelId, optionally stability, similarity, style, speed, seed.
For long text use the long-form endpoint: up to 50,000 characters, auto-chunked with context continuity, returning one file and a full timeline.
3. Pick voices and models
- Voice IDs come from your library — community, cloned and designed voices all work
- Models: flagship (expressive, emotion tags) / multilingual standard / flash (half price, low latency) — see choosing a model
- Brand names and terms go in a pronunciation dictionary, defined once, applied everywhere
4. Billing and failures
Each call deducts credits per operation, matching the studio's button prices; upstream failures refund in full automatically — your code never handles refunds. Insufficient balance returns a clear error; buy a plan as needed.
5. Common errors
| Symptom | Cause | Fix | | --- | --- | --- | | 401 | Invalid or revoked key | Create a new key | | Insufficient credits | Balance is zero | Top up or use a cheaper model | | Text too long | Over the model's per-request cap | Use the long-form endpoint | | Wrong accent | Voice doesn't match the language | Use a native voice per language — see multilingual accents |