Migrate from Fish Audio

To switch from Fish Audio to Gradium, you need a handful of mechanical edits: point requests at Gradium URLs, send x-api-key instead of a Bearer token, rename a few request fields, and replace MessagePack WebSocket events with JSON messages, which removes the msgpack dependency.

Why choose Gradium over Fish Audio

Official voice catalog. Gradium’s flagship voices are first-party voices built with voice experts and researchers for every supported language. Fish Audio’s library is community-uploaded models owned by individual accounts.
Streaming STT. Gradium transcribes live audio over WebSocket with semantic VAD and adaptive delay for turn-taking. Fish Audio only offers batch transcription.
Speech-to-speech translation. Gradium’s S2S endpoint translates live speech into another language over one WebSocket: audio streams in, translated audio and transcript stream out. Fish Audio has no equivalent.
JSON everywhere. All Gradium WebSocket messages are JSON, so clients drop the MessagePack dependency and work directly with wscat, browsers, and standard libraries.
Browser-safe auth. Short-lived tokens from GET /api/api-keys/token let browser and mobile clients connect without embedding API keys; see Browser WebSockets.
Production controls. Multiplexing with client_req_id, pronunciation dictionaries, text rewriting, and telephony formats (ulaw_8000, alaw_8000) are built into the same endpoints.

Endpoint Swap

Flow	Fish Audio	Gradium
One-shot TTS	`POST https://api.fish.audio/v1/tts`	`POST https://api.gradium.ai/api/post/speech/tts`
Streaming TTS	`wss://api.fish.audio/v1/tts/live`	`wss://api.gradium.ai/api/speech/tts`
Voice cloning	`POST https://api.fish.audio/model`	`POST https://api.gradium.ai/api/voices/`
List voices	`GET https://api.fish.audio/model`	`GET https://api.gradium.ai/api/voices/`
Batch STT	`POST https://api.fish.audio/v1/asr`	`POST https://api.gradium.ai/api/post/speech/asr`
Streaming STT	Not available	`wss://api.gradium.ai/api/speech/asr`

Auth Mapping

Fish Audio	Gradium
`Authorization: Bearer $FISH_API_KEY`	`x-api-key: $GRADIUM_API_KEY`
`model` header (`s1`, `s2-pro`, `s2.1-pro`)	`model_name` field, default `default`
API key in browser clients	Short-lived `?token=...`; see Browser WebSockets.

model_name goes in the request body or setup message; default always points at the current recommended model, so most integrations never set it.

Voice Catalog

Gradium’s flagship voice catalog covers all supported languages, including French, German, Spanish, and Portuguese, plus regional variants such as Brazilian Portuguese and Mexican Spanish.

Fish Audio	Gradium
Community-uploaded clones, per-user ownership	First-party flagship voices
Availability depends on the uploading account	Stable `voice_id` values
Quality varies with the uploader’s reference audio	Consistent studio-quality recordings
Discovery by search, tags, and popularity	Curated list with description, country, and gender

Pick a replacement voice_id per language from the voice library, or clone a voice you own as a private custom voice (see Voice Cloning Migration).

Gradium POST TTS

With only_audio: true, the response is raw audio bytes, same as Fish Audio’s /v1/tts.

Gradium

curl -L -X POST https://api.gradium.ai/api/post/speech/tts \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Gradium.",
    "voice_id": "YTpq7expH9539ERJ",
    "output_format": "wav",
    "only_audio": true
  }' \
  > output.wav

TTS Field Mapping

Fish Audio field	Gradium field
`text`	`text`
`reference_id`	`voice_id`
`model` header	`model_name`
`format` + `sample_rate`	`output_format` string
`latency` (`low`, `balanced`, `normal`)	Not needed; use the WebSocket endpoint for low latency
`chunk_length` / `min_chunk_length`	Send text in chunks over WebSocket; place `<flush>` at natural boundaries
`normalize`	`json_config.rewrite_rules`; see Text Rewriting
`prosody.speed`	`json_config.padding_bonus` (negative is faster, positive is slower)
`temperature`	`json_config.temp`
`top_p` / `repetition_penalty`	No direct equivalent; tune `temp` and `cfg_coef`
`references` (inline zero-shot audio)	Create a voice once with `POST /voices/`, then reuse its `voice_id`

output_format is one string instead of separate format and sample-rate fields: wav, pcm, opus, ulaw_8000, alaw_8000, or explicit PCM rates such as pcm_16000 and pcm_44100.

Gradium does not return MP3. Replace format: "mp3" with wav for file output or opus for compressed streaming.

WebSocket TTS Migration

Fish Audio’s /v1/tts/live socket uses MessagePack events. Gradium’s TTS socket uses JSON text messages.

Gradium messages

{"type":"setup","voice_id":"YTpq7expH9539ERJ","model_name":"default","output_format":"pcm"}
{"type":"text","text":"Hello from Gradium."}
{"type":"end_of_stream"}

Fish Audio event	Gradium message
`start` with a `request` config object	`setup` with `voice_id`, `model_name`, `output_format`
`text`	`text`
`flush`	`<flush>` tag inside a `text` message
`stop`	`end_of_stream`
`audio` (binary payload)	`audio` (base64 payload in JSON)
`finish` with `reason`	`end_of_stream` server message

Gradium replies with ready after setup, streams audio messages, and finishes with its own end_of_stream. For several logical requests on one socket, add client_req_id to each message and set close_ws_on_eos: false; see Multiplexing.

Voice Cloning Migration

Fish Audio clones a voice by creating a model from uploaded samples. Gradium uses one POST /voices/ call; the returned uid is the voice_id for any TTS request.

Gradium

curl -X POST https://api.gradium.ai/api/voices/ \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -F "audio_file=@voice_sample.wav" \
  -F "name=My Custom Voice" \
  -F "language=en"

Fish Audio field	Gradium field
`voices` (one or more audio files)	`audio_file` (one file; about 10 seconds of clean speech)
`texts` (transcripts of the samples)	Not required
`title`	`name`
`train_mode` (`fast`)	Not required; extraction runs on upload
`visibility`	Not required; voices are private to your account
`type: "tts"`	Not required
`enhance_audio_quality`	Not required
Returned `_id`	Returned `uid`, used as `voice_id`

Manage clones with GET, PUT, and DELETE on /voices/{voice_uid}; see Custom Voices.

STT Migration

Fish Audio’s /v1/asr takes MessagePack or multipart uploads and returns one JSON object. Gradium’s POST STT endpoint takes raw audio bytes as the request body and streams newline-delimited JSON messages.

Gradium

curl -X POST https://api.gradium.ai/api/post/speech/asr \
  -H "x-api-key: $GRADIUM_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @recording.wav

Fish Audio ASR concept	Gradium STT equivalent
MessagePack or multipart request body	Raw audio bytes with `Content-Type: audio/wav`, `audio/pcm`, or `audio/ogg`
`language` hint	`language` query parameter, or `json_config.language` on WebSocket
`text` in the response	Concatenate streamed `text` messages
`segments` with start and end times	Per-message segment timing
`ignore_timestamps`	Timing is always included in streamed messages
No streaming option	`wss://api.gradium.ai/api/speech/asr` with semantic VAD `step` messages

For live transcription, use the WebSocket endpoint; it emits step messages with inactivity_prob for turn-taking. See Speech-to-Text.

Adapter Checklist

Replace Fish Audio URLs with the matching Gradium endpoints.
Change auth from Authorization: Bearer to x-api-key, or short-lived ?token=... for browser WebSockets.
Drop the model header; set model_name only for a specific model.
Rename reference_id to voice_id, using flagship voices from the voice library.
Collapse format and sample_rate into one output_format string; replace MP3 with wav or opus.
Replace MessagePack events (start, text, stop) with JSON messages (setup, text, end_of_stream).
Re-create cloned voices with POST /voices/ and use the returned uid values.
Move prosody and sampling knobs into json_config; see Voice Settings.
For batch STT, send raw audio bytes and read streamed JSON messages.

Next steps

Gradium TTS WebSocket guide

Streaming setup messages, audio messages, flush, and timestamps.

Custom Voices

Create, update, and manage cloned voices from reference audio.

Voice Settings

Speed, temperature, and similarity controls via json_config.

Speech-to-Text

Streaming transcription with semantic VAD and flush.

Getting Started

Text-to-Speech

Speech-to-Text

Speech-to-Speech

Shared

Real-time Recipes

Migrations

Voices

Self-Hosted

Resources

Migrate from Fish Audio

Why choose Gradium over Fish Audio

Endpoint Swap

Auth Mapping

Voice Catalog

Gradium POST TTS

TTS Field Mapping

WebSocket TTS Migration

Voice Cloning Migration

STT Migration

Adapter Checklist

Next steps

Gradium TTS WebSocket guide

Custom Voices

Voice Settings

Speech-to-Text

​Why choose Gradium over Fish Audio

​Endpoint Swap

​Auth Mapping

​Voice Catalog

​Gradium POST TTS

​TTS Field Mapping

​WebSocket TTS Migration

​Voice Cloning Migration

​STT Migration

​Adapter Checklist

​Next steps

Gradium TTS WebSocket guide

Custom Voices

Voice Settings

Speech-to-Text

Why choose Gradium over Fish Audio

Endpoint Swap

Auth Mapping

Voice Catalog

Gradium POST TTS

TTS Field Mapping

WebSocket TTS Migration

Voice Cloning Migration

STT Migration

Adapter Checklist

Next steps