How to Implement Fish Audio: API, Voice Cloning, Streaming, and What It Actually Costs

In the previous post I looked at what Fish Audio is as a company and why three of its models are open while the flagship sits behind a paid API. This one is the other half: how you actually wire it into something. Authentication, the endpoint, the Python SDK, both routes to voice cloning, streaming that starts speaking before your language model has finished thinking, and the pricing arithmetic that decides whether any of it is affordable at your volume. Everything below comes from the current documentation rather than from memory.

The smallest thing that works

Before installing anything, confirm your key works with a single request. The endpoint is POST https://api.fish.audio/v1/tts, authentication is a standard bearer token, and the response is a chunked audio stream rather than a JSON envelope containing a URL.

# The model is selected with a header, which is unusual enough to trip people up.
# s2.1-pro-free costs nothing, so use it while you are still experimenting.

curl --request POST \
  --url https://api.fish.audio/v1/tts \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'model: s2.1-pro-free' \
  --data '{"text": "Hello! Welcome to Fish Audio."}' \
  --output hello.mp3

Two details in that request matter more than they look. The model header is how you pick the engine, so a request that seems to ignore your model choice is usually one where the value was put in the JSON body instead. And the response streams as audio bytes directly, so if you are debugging by printing the body you will get binary noise rather than an error message.

The Python SDK

For anything beyond a smoke test the SDK is less work. One thing to note before you start: the package you install and the module you import are not spelled the same way, which costs people a few confused minutes.

pip install fish-audio-sdk      # note the hyphens
export FISH_API_KEY=your_api_key_here

from fishaudio import FishAudio          # but the module has no hyphens
from fishaudio.utils import save

client = FishAudio()                     # reads FISH_API_KEY from the environment
# or be explicit: FishAudio(api_key="...")
# AsyncFishAudio is the asyncio variant

audio = client.tts.convert(text="Hello from Fish Audio!")
save(audio, "out.mp3")

Output format, sample rate and speaking rate are all adjustable. The default format is mp3, which is right for delivery to a browser and wrong for anything you intend to process further, since you want uncompressed frames for that.

from fishaudio.types import TTSConfig

# wav or pcm when the audio feeds another system, mp3 or opus when it feeds a person
audio = client.tts.convert(
    text="High quality narration for the archive.",
    config=TTSConfig(format="wav", sample_rate=44100),
)

# Speed accepts 0.5 to 2.0. Small adjustments read as natural, large ones do not.
brisk = client.tts.convert(text="Speaking a little faster.", speed=1.2)

# Pick a specific voice by id
branded = client.tts.convert(
    text="This uses a specific voice.",
    reference_id="9a9cf47702da476aa4629e2506d4a857",
)

For long documents, use stream rather than convert. It yields chunks instead of building the entire clip in memory, which matters once you are narrating something book length.

with open("chapter.mp3", "wb") as f:
    for chunk in client.tts.stream(text=very_long_passage):
        f.write(chunk)

Which model to use, and the free tier that is not a downgrade

This is the part worth reading carefully, because the naming hides something genuinely useful. The documentation describes s2.1-pro as the recommended production model, with improved quality, latency and throughput over the previous S2-Pro. It describes s2.1-pro-free as the same model at zero cost, intended for testing, prototyping and development.

The practical consequence is that you can evaluate the actual production model against your real content, in your real languages, at no cost, before committing a single rupee or dollar. That removes the usual excuse for benchmarking on a weaker tier and then being surprised in production. Do your quality testing on the free model, and change one header value when you go live.

Voice cloning, both ways

There are two approaches and they suit different products. Create a persistent voice model when the same voice will be reused, since you clone once and then reference an id forever. Use zero shot references when the voice is supplied per request and there is nothing to keep.

# Route 1: a reusable voice model. Clone once, reference the id afterwards.
with open("sample.wav", "rb") as f:
    voice = client.voices.create(
        title="Narrator",
        voices=[f.read()],
        description="Cloned from a studio sample",
        visibility="private",          # private is the default; unlist and public also exist
    )

print(voice.id, voice.state)

audio = client.tts.convert(
    text="Now I speak in the cloned voice.",
    reference_id=voice.id,
)

# Route 2: zero shot. Nothing is stored, the reference travels with the request.
from fishaudio.types import ReferenceAudio

with open("reference.wav", "rb") as f:
    audio = client.tts.convert(
        text="This will sound like the reference voice.",
        references=[ReferenceAudio(
            audio=f.read(),
            text="The exact words spoken in the reference clip.",
        )],
    )

Note the transcript in the zero shot path. You pass both the audio and the words actually spoken in it, and accuracy there measurably affects the result. A transcript that does not match the audio produces a worse clone than no attempt at all.

On source material, the documentation is specific: WAV, MP3, M4A or Opus, a minimum of ten seconds per clip, and one to two minutes of clear single speaker speech as the optimum. That last figure is worth respecting. Ten seconds works, but the difference between the minimum and a proper minute of clean audio is audible, and it is the cheapest quality improvement available. Audio enhancement for noisy recordings is on by default.

Streaming, and speaking while the model is still thinking

For voice agents and assistants, the HTTP streaming path is still too slow, because it cannot begin until your language model has produced the complete text. The websocket mode removes that wait entirely. It accepts a generator of text tokens and starts emitting audio as the words arrive.

from fishaudio import FishAudio
from fishaudio.utils import play

client = FishAudio()

def llm_tokens():
    # In production this yields tokens from your LLM stream, not a fixed list
    for token in ["The ", "first ", "move ", "sets ", "everything ", "in ", "motion."]:
        yield token

for chunk in client.tts.stream_websocket(llm_tokens(), reference_id="YOUR_VOICE_ID"):
    play(chunk)

This is the single most important pattern in the whole integration for anything conversational. Without it, perceived latency is the language model generation time plus the synthesis time. With it, the two overlap, and the user hears the first words while the model is still composing the rest. That difference is usually the gap between an assistant that feels responsive and one that feels broken.

There is a latency parameter with two settings, and the documentation attaches actual numbers to them. normal is described as best quality at roughly 500 milliseconds, and balanced as good quality at roughly 300 milliseconds. For anything conversational that 200 millisecond difference is worth more than the quality increment, and the documentation itself recommends balanced mode when audio is taking too long to start. Reserve normal for pre rendered audio where nobody is waiting. An async client, AsyncFishAudio, takes async generators in the same shape.

What it costs, in numbers you can plan with

Billing is per million UTF-8 bytes rather than per character or per second, which is awkward to reason about until you convert it. The documentation puts one million UTF-8 bytes at roughly 180,000 English words, or about 12 hours of speech. At 15 dollars per million, that gives some useful reference points.

Be careful with the UTF-8 detail if you work in non Latin scripts. Billing counts bytes, not characters, and Sinhala, Tamil, Chinese, Japanese, Arabic and similar scripts use multiple bytes per character. Text that looks the same length as an English sentence can cost two or three times as much, which is worth modelling before you launch a localised product rather than discovering it on an invoice.

The other limit to plan around is concurrency rather than volume. Rate limits are expressed as simultaneous requests and rise with lifetime spend.

Five concurrent requests is comfortable for a content pipeline and tight for anything user facing at scale, so queue your work rather than firing requests as they arrive. A simple worker pool sized to your tier, with retries on rejection, prevents the failure mode where a traffic spike turns into a wall of errors.

The production checklist

Four things separate a working prototype from something you can leave running.

1. Cache on a hash of text + voice + parameters.
   Applications repeat far more utterances than anyone expects,
   and cached audio costs nothing to serve.

2. Normalise text before synthesis.
   Expand currency, dates, units and known acronyms into the words
   you want spoken. This removes most reported quality complaints.

3. Queue to your concurrency tier.
   Five simultaneous requests on the starter tier. Size a worker pool
   to match and retry on rejection instead of failing the user.

4. Log voice provenance.
   Which voice, which account, which authorisation, retained.
   You cannot answer the only question that matters after an incident
   without it.

Putting it together

The integration itself is genuinely small. A bearer token, one endpoint, a header to pick the model, and a handful of parameters. The work that decides whether the result is any good sits either side of that call: normalising your text so numbers and acronyms are spoken correctly, caching so you are not paying twice for the same sentence, queueing to your concurrency tier, streaming from your language model so the two stages overlap, and keeping an honest record of whose voice you are using and why. Start on the free model with your worst content, and only move to the paid tier once you know exactly what you are buying.