Text to Speech API: Build Voice Features Fish Audio
Plan a text to speech API integration: authentication, request design, streaming audio, retries, latency, security and generation costs for production applications.
A text to speech API lets your application send text and receive audio without asking a person to open the browser workspace. The production decision is not only which endpoint to call: you need to choose streaming or background generation, protect the key, handle retries and keep latency inside the experience you are building.
What should the API integration produce?
The output is an audio asset or stream that another part of your product can play. The input should be clean text plus the voice and delivery settings the current contract supports. Treat the script as the source of truth and store it with the voice identifier so a later request can be reproduced.
Common integrations include:
- A conversational assistant that streams replies.
- A course platform generating audio versions of lessons.
- A media pipeline turning approved scripts into episode files.
- An accessibility feature that reads product pages or documents.
The Fish Audio API overview explains access and credits. This page focuses on the engineering decisions around the text-to-speech path.
Stream or generate a complete file?
Stream when a listener is waiting. A voice agent should start audio while the rest of the answer is still being generated. A complete file is better when the caller can process in the background and the final asset must be inspected, stored or transcoded.
| Use case | Preferred path | Why |
|---|---|---|
| Voice assistant | Streamed audio | Minimal time to first syllable |
| Course module | Background job | Human review before publication |
| Short social video | One file per script block | Easy re-edits and file management |
| Long audiobook | Paragraph or chapter jobs | Cheap partial regeneration |
Do not send an entire novel through a conversational path. Chunk by chapter and paragraph, then join carefully so pauses and pronunciation remain controlled.
How do you secure text to speech keys?
Keep the private API key on a trusted server or worker. Browser code may send text to your backend, but it must not receive the provider secret. Use one key per environment and one key per workload when the product supports it.
| Control | Minimum practice |
|---|---|
| Storage | Secret manager or encrypted environment variable |
| Environments | Separate staging and production keys |
| Rotation | Revoke and replace on exposure or staff change |
| Logging | Never print the key or full authorization header |
| Access | Restrict which services can create or reveal keys |
The workspace key workflow is covered in the API overview. Always follow the current request contract shown there rather than copying an unverified endpoint from a third-party tutorial.
How do you handle errors and retries?
Separate four failure groups:
- Validation: text missing, unsupported option or oversized input. Fix the request.
- Authentication: missing, revoked or unavailable key. Do not retry blindly.
- Rate or concurrency limits: queue, back off and alert when saturation persists.
- Transient server or network failure: retry a bounded number of times with exponential backoff.
Attach a request identifier to every job and persist the status. If a worker crashes after generation but before saving the audio, your queue needs to know whether to retry or recover the existing result.
How do you control latency?
Use warm server connections and avoid a cold start before every reply. Keep prompts short, return a first sentence quickly and chunk only at semantic boundaries. Measure end-to-end time to audible audio, not just the provider response time.
The real-time text to speech guide includes a useful latency budget. For a conversational product, combine it with the voice agent guide, which covers interruption and turn-taking.
What does API generation cost?
One credit covers about 1,000 characters of generated speech. API access is part of the $99 Studio pack, which includes 15,000 credits and the highest concurrency available here. That is enough for roughly 15 million characters when all credits are used for speech.
| Monthly workload | Approximate characters | Approximate credits |
|---|---|---|
| 1,000 short replies | 300,000 | 300 |
| 100 course modules | 500,000 | 500 |
| 50 narrated episodes | 750,000 | 750 |
| 10 long audiobooks | 6,000,000 | 6,000 |
Retries, failed jobs and test traffic belong in the estimate. Keep a small buffer for pronunciation fixes and script changes instead of budgeting exactly to the expected character count.
What should you test before launch?
- Authentication failure, invalid text and quota exhaustion.
- One complete file path and one streamed path.
- Time to first audio from a realistic region.
- Concurrent jobs at expected and peak load.
- Text containing numbers, names, URLs and delivery tags.
- Storage, retention and deletion rules for generated audio.
- Browser playback on mobile, desktop and a slow connection.
Add a manual listening pass before publishing customer-facing audio. A request can succeed while a name is mispronounced or a sentence loses the intended emphasis.
How should you roll out the integration?
Start with a single non-critical workflow and a fixed set of scripts. Measure time to first audio, completion rate, retry rate and listening quality before connecting the API to customer-facing traffic. Keep the existing voice path available as a fallback during the first release.
When the test is stable, add one workload at a time. A background audiobook pipeline and a live voice agent have different latency, retry and storage requirements, so a shared integration layer should expose those differences instead of hiding them behind one generic request function.
Finally, document the voice, settings, script revision and job identifier for every approved production asset. That record reduces support time, prevents accidental duplicate charges and makes a voice or pronunciation regression easier to diagnose.
Frequently asked questions
What can I build with a text to speech API?
A text to speech API adds generated voice to products, agents, learning tools, media pipelines and accessibility features. The application sends text and receives audio that it can stream, store or serve to a user.
How do I authenticate a text to speech API?
Use the key workflow documented for the current product and keep the secret on your server. Separate staging and production keys, store them in a secret manager, and never expose a private key inside browser code.
Should I stream audio or wait for one file?
Stream when a person is waiting to hear a reply. Use a complete file when generating a podcast, audiobook, lesson or other asset that can be processed in the background.
How should text to speech API failures be retried?
Retry transient network or server failures with exponential backoff and a small limit. Do not retry validation or authentication errors without changing the request, and make the operation idempotent where your queue supports it.
How is API usage priced?
Generation spends credits based on speech volume: one credit covers about 1,000 characters. API access is included in the $99 Studio pack, which carries 15,000 credits and the highest concurrency on this site.