Migrate from ElevenLabs

import os

from elevenlabs import ElevenLabs

client = ElevenLabs(
    base_url="https://api.fish.audio/compat/elevenlabs",
    # sent as the standard xi-api-key header
    api_key=os.environ["FISH_AUDIO_API_KEY"],
)

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({
  baseUrl: "https://api.fish.audio/compat/elevenlabs",
  apiKey: process.env.FISH_AUDIO_API_KEY, // sent as the standard xi-api-key header
});

1. Voices are your Fish voices. ElevenLabs preset names (Rachel, …) don’t exist here. Pass the ID of a voice from your Fish voice library — client.voices.get_all() lists them (Voice library) — or default (also -) for the model’s default voice.
2. Keep your model_id, or pick a Fish model. Existing values like eleven_multilingual_v2 are accepted as-is and served by Fish s2.1-pro, so your code runs unchanged. To choose a different model, pass its Fish name, e.g. fish-audio/s2-pro — see Models.

​

Text to speech

audio = b"".join(client.text_to_speech.convert(
    voice_id="default",
    text="Hello from Fish Audio!",
    model_id="eleven_multilingual_v2",
    output_format="mp3_44100_128",
))

const stream = await client.textToSpeech.convert("default", {
  text: "Hello from Fish Audio!",
  modelId: "eleven_multilingual_v2",
  outputFormat: "mp3_44100_128",
});
const chunks = [];
for await (const chunk of stream) chunks.push(chunk);
const audio = Buffer.concat(chunks);

curl "https://api.fish.audio/compat/elevenlabs/v1/text-to-speech/default?output_format=mp3_44100_128" \
  -H "xi-api-key: $FISH_AUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Fish Audio!",
       "model_id": "eleven_multilingual_v2"}' \
  --output hello.mp3

​

Output formats

​

Timestamps

• normalizedAlignment is identical to alignment, field for field. Fish synthesizes the text as given, so there is no normalization pass to report; the same alignment is sent under both keys. Pick either — don’t diff them expecting to recover normalization.
• On the WebSocket, the milliseconds are absolute on the session timeline (alignment frames need ?sync_alignment=true — see Realtime input streaming), not relative to the current turn. Turn two of a stream-input session starts where turn one’s audio ended (~1022 ms, say), not back at 0. That is what lets a client concatenate every frame’s audio and alignment and have the captions line up. Don’t add your own per-turn offset — you would double-count it.

​

Realtime input streaming (WebSocket)

1. Send the init message — a single-space text, plus optional voice_settings.
2. Send text chunks; try_trigger_generation or flush forces synthesis now.
3. Send an empty-string text to finish.

• A normal frame is {"audio": "<base64>"}. Timing data is opt-in: add ?sync_alignment=true to the handshake URL and frames become {"audio": …, "alignment": {…}, "normalizedAlignment": {…}}. With alignment on, a turn’s first audio arrives only after its first text chunk has fully synthesized — expect a later first byte than the default mode. Both alignment keys are omitted when there is nothing to report for that chunk, so treat them as optional rather than indexing into them blindly.
• With sync_alignment, a turn can end with an audio-less frame carrying only alignment and normalizedAlignment — trailing punctuation and whitespace that no audio segment spoke. Code that assumes every frame has audio will throw on it.
• Errors arrive in band as {"error": "…", "code": …} on the open socket — the code is an HTTP status, or a WebSocket close code for transport-level limits (an over-1 MiB text buffer closes the socket with 1009).
• The stream ends with {"isFinal": true} — a frame with no audio — followed by a close.

from elevenlabs import VoiceSettings

def sentences():
    yield "Streaming text, "
    yield "sentence by sentence."

audio = b"".join(client.text_to_speech.convert_realtime(
    voice_id="default",
    text=sentences(),
    model_id="eleven_multilingual_v2",
    voice_settings=VoiceSettings(stability=0.5, speed=1.0),
))

​

Speech to text

result = client.speech_to_text.convert(
    file=open("meeting.wav", "rb"),
    model_id="scribe_v1",  # accepted and ignored — Fish's ASR model is used
    language_code="zh",
)

import fs from "node:fs";

const buf = fs.readFileSync("meeting.wav");
const result = await client.speechToText.convert({
  file: new File([buf], "meeting.wav"),
  modelId: "scribe_v1", // accepted and ignored — Fish's ASR model is used
});
console.log(result.text);

curl https://api.fish.audio/compat/elevenlabs/v1/speech-to-text \
  -H "xi-api-key: $FISH_AUDIO_API_KEY" \
  -F model_id=scribe_v1 \
  -F file=@meeting.wav

• language_probability is always 1.0.
• words[].logprob is always 0.
• words[].speaker_id is always null; requesting diarization returns an explicit error instead.

​

Realtime STT

​

Voice library

• GET /v1/voices, GET /v2/voices, GET /v1/voices/{id} — your voices in the ElevenLabs Voice shape (category: "cloned", tags mapped to labels).
• GET /v1/models — the Fish model catalog in the ElevenLabs shape.
• GET /v1/user — a stub for SDK health checks.

voices = client.voices.get_all()
for v in voices.voices:
    print(v.voice_id, v.name)

const voices = await client.voices.search();
for (const v of voices.voices) console.log(v.voiceId, v.name);

curl https://api.fish.audio/compat/elevenlabs/v1/voices \
  -H "xi-api-key: $FISH_AUDIO_API_KEY"

​

Going further