Fish Audio Python SDK

To use the Fish Audio SDK, install the fishaudio package via pip and configure your API key using the FISH_API_KEY environment variable.

# Install the package
pip install fishaudio

# Set your API key
export FISH_API_KEY="your_api_key"

The SDK provides both synchronous (FishAudio) and asynchronous (AsyncFishAudio) clients for generating audio from text.

# Synchronous usage
from fishaudio import FishAudio
from fishaudio.utils import play, save

client = FishAudio()

# Generate audio
audio = client.tts.convert(text="Hello, world!")

# Play or save
play(audio)
save(audio, "output.mp3")

# Asynchronous usage
import asyncio
from fishaudio import AsyncFishAudio
from fishaudio.utils import play, save

async def main():
    client = AsyncFishAudio()
    audio = await client.tts.convert(text="Hello, world!")
    play(audio)
    save(audio, "output.mp3")

asyncio.run(main())

Install the core SDK using pip:

pip install fish-audio-sdk

If you require audio playback utilities (like play() and save()), install the package with the [utils] extra:

pip install fish-audio-sdk[utils]

Note on Versioning: The SDK has transitioned to a new versioning scheme. To ensure you receive updates, use fish-audio-sdk>=1.0.0 in your dependency constraints.

pip install fish-audio-sdk

# With audio playback utilities
pip install fish-audio-sdk[utils]

You can authenticate using an API key obtained from fish.audio/app/api-keys.

There are two ways to provide your key:

1. Environment Variable: Set FISH_API_KEY in your shell.
2. Directly in Code: Pass the api_key argument when initializing the FishAudio client.

export FISH_API_KEY=your_api_key_here

from fishaudio import FishAudio

client = FishAudio(api_key="your_api_key")

To perform instant voice cloning, provide a list of ReferenceAudio objects to your TTS configuration. This allows the model to mimic the style and characteristics of the provided samples.

Each ReferenceAudio requires:

• audio: The raw bytes of the reference audio file.
• text: The exact transcription of what is spoken in the reference audio, including punctuation, to ensure proper prosody.

from fishaudio.types.tts import ReferenceAudio

ref = ReferenceAudio(
    audio=open("sample.wav", "rb").read(),
    text="Hello, this is the reference voice speaking."
)

# Use in config
# config = TTSConfig(references=[ref])

TTS requests can be configured using a TTSConfig object, but most common parameters can be passed directly to the method calls for easier use and higher precedence.

Supported direct parameters:

• text: The string to synthesize.
• reference_id: A specific voice reference ID.
• references: A list of ReferenceAudio objects.
• format: Audio format ("mp3", "wav", "pcm", or "opus").
• latency: Latency mode ("normal" or "balanced").
• speed: A float multiplier for speech speed (e.g., 1.5).
• model: The TTS model to use (defaults to "s2.1-pro").
• config: A TTSConfig instance for advanced settings.
• request_options: Request-level overrides.
• ws_options: WebSocket-specific options (for stream_websocket).

Precedence Rule: Direct parameters > TTSConfig values.

The Fish Audio clients use lazy-loaded namespace properties to organize operations. Depending on whether you use FishAudio or AsyncFishAudio, you can access the following service clients:

• tts: Text-to-Speech operations.
• asr: Automatic Speech Recognition (speech-to-text) operations.
• voices: Voice management and listing operations.
• account: Account and billing operations.

The AsyncVoicesClient provides the same functionality as VoicesClient but uses async/await syntax for non-blocking operations. Use this when integrating with asynchronous frameworks or performing multiple concurrent voice operations.

Methods available:

• list()
• get()
• create()
• update()
• delete()

The Voice class represents a TTS (Text-to-Speech) or SVC (Singing Voice Conversion) model available for synthesis. When performing TTS tasks, the id field (aliased from _id) should be used as the reference_id.

Key attributes include:

• type: Either "svc" or "tts".
• state: The current status of the model (e.g., "ready", "training", "failed").
• languages: A list of supported language codes (e.g., ["en", "zh"]).
• visibility: The visibility setting ("public", "private", or "unlist").
• author: An Author object containing the creator's details.
• samples: A list of Sample objects providing audio demonstrations of the voice.

from fishaudio.types.voices import Voice

# Example of accessing voice properties
# voice: Voice = ...
# print(f"Using voice: {voice.title} (ID: {voice.id})")
# print(f"Supported languages: {voice.languages}")

Install the fishaudio package using pip. To authenticate, set the FISH_API_KEY environment variable or include it in a .env file.

pip install fishaudio
export FISH_API_KEY="your_api_key"

Import FishAudio from the fishaudio package. It is recommended to use dotenv to load your FISH_API_KEY from a .env file.

from dotenv import load_dotenv
from fishaudio import FishAudio

load_dotenv()
client = FishAudio()

Use client.asr.transcribe() to convert audio files into text. You can specify the language and access timestamped segments in the result.

# Transcribe audio
with open("audio.wav", "rb") as f:
    result = client.asr.transcribe(audio=f.read(), language="en")

print(result.text)

# Access timestamped segments
for segment in result.segments:
    print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")