Skip to main content
Technology & EngineeringVoice Speech Services28 lines

Integrate Fish Audio Text-to-Speech

Synthesize and verify speech with Fish Audio using a permitted voice, controlled request parameters, and checks for truncated or invalid audio.

Quick Summary8 lines
Choose a permitted voice, the language, target format, and intended output use. Use a stock voice or a voice with documented consent for the proposed synthesis and distribution. Keep the reference recording and consent record access-controlled. A sample available online cannot establish permission to reproduce its speaker. Use synthetic scripts to validate the request before transmitting customer content.

## Key Points

- [Fish Audio TTS endpoint](https://docs.fish.audio/api-reference/endpoint/openapi-v1/text-to-speech)
- [Fish Audio speech engine repository](https://github.com/fishaudio/fish-speech)
skilldb get voice-speech-services-skills/fish-audio-ttsFull skill: 28 lines
Paste into your CLAUDE.md or agent config

Integrate Fish Audio Text-to-Speech

Establish the audio contract

Choose a permitted voice, the language, target format, and intended output use. Use a stock voice or a voice with documented consent for the proposed synthesis and distribution. Keep the reference recording and consent record access-controlled. A sample available online cannot establish permission to reproduce its speaker. Use synthetic scripts to validate the request before transmitting customer content.

Pick a short calibration script with a proper noun, number, punctuation break, and final line. Save the script ID, model selection, voice ID, format, and non-default settings alongside the sample. Determine which pronunciation changes belong in the text and which should use the selected model's documented controls. Start with one voice and a short utterance to keep the number of variables small.

Use the documented endpoint shape

For the hosted REST workflow, read the current POST /v1/tts contract for the chosen model. Use the bearer credential on the server. Pin a documented model header in an allowlist and verify authorization and the budget before sending. The current REST endpoint falls back to s2.1-pro if the header is omitted or unrecognized. If the approved target is the free developer tier, require its exact documented model ID, and fail locally if it is missing or unsupported. Pass the desired supported format with text in the JSON body. A pre-created voice uses reference_id. Voice-reference input and multi-speaker syntax depend on model support and have different shapes. For a single-speaker test, use a scalar permitted voice ID and avoid mixing it with reference audio.

Check the response before decoding. Inspect status, expected content type, bounded size, and whether audio bytes actually arrive. Save to an isolated temporary destination and verify with an audio decoder. Promote to the deliverable path only after validation. A JSON error body saved under an MP3 extension must fail the test. If the caller streams to a player, define a distinct incomplete state for a dropped connection or decode failure. Retries after playback starts need a policy that avoids duplicated speech.

Handle unauthorized or invalid requests by surfacing a useful configuration error without dumping headers or speech text. Respect the provider's documented retry guidance for throttling and transient errors. Keep retry budgets bounded, and avoid automatically retrying an ambiguous network failure in a way that can double bill a long job. For long text, plan semantic breaks and use the same segmentation across comparisons. Stitch decoded audio with a supported encoder and check joins for missing words or duplicated fragments.

Listen to the complete calibration output. Record pronunciation, pacing, clipping, unexpected silence, and whether the final line is intact. Run a second script with representative text and a separate failure fixture with no valid audio. For streaming, measure time to first playable audio and full completion separately. Preserve the approved original audio and record model or format changes in the output metadata.

References

Install this skill directly: skilldb add voice-speech-services-skills

Get CLI access →