Fish Audio Python SDK

1.3.0 · active · verified Thu Apr 16

The `fish-audio-sdk` is the official Python client library for the Fish Audio API, currently at version 1.3.0. While the `fish-audio-sdk` PyPI package is still actively maintained, from version 1.0.0 onwards, it installs the newer, client-based `fishaudio` module, which is the recommended and more robust API for interacting with Fish Audio services. Releases are frequent, often several times a month, reflecting continuous development and feature additions.

Common errors

```
ModuleNotFoundError: No module named 'fishaudio'
```
cause Attempting to import `fishaudio` when `fish-audio-sdk` is installed at a version prior to 1.0.0, or if the package is not installed correctly.

fix Ensure `fish-audio-sdk` is installed and updated to version 1.0.0 or higher: `pip install --upgrade fish-audio-sdk`. The `fishaudio` module is only available after this version.
```
Code expects TTS chunks but gets complete audio.
```
cause This is not an error string, but a common logic bug. It happens when migrating from older SDK versions or examples that used to return audio chunks from `convert()` to versions 1.0.0+ where `convert()` returns a single byte object.

fix If you require audio chunks, switch from `client.tts.convert()` to `client.tts.stream()` or `client.tts.stream_websocket()`.
```
Because fish-audio-sdk==2025.6.3 was yanked (reason: Break Change)
```
cause Attempting to install or use `fish-audio-sdk` version `2025.6.3`, which was explicitly yanked from PyPI due to a major breaking change in API and internal module structure.

fix Avoid pinning to version `2025.6.3`. Instead, install `fish-audio-sdk>=1.0.0` to get the updated client and API, or pin to a specific `1.x.x` version like `fish-audio-sdk==1.3.0`.

Warnings

breaking Migration from legacy `fish_audio_sdk` module to `fishaudio` module (introduced with `fish-audio-sdk` v1.0.0). While the PyPI package name remains `fish-audio-sdk`, the import path changed. Version `2025.6.3` was specifically yanked due to these breaking changes.
Fix: Ensure `fish-audio-sdk` is updated to version 1.0.0 or higher (`pip install --upgrade fish-audio-sdk`) and update your imports from `from fish_audio_sdk import Session` to `from fishaudio import FishAudio`.
deprecated Speech API versions 1.5 and 1.6 are deprecated and have been re-routed. While still functional, users should anticipate eventual removal or breaking changes related to these specific model versions.
Fix: Consult the latest Fish Audio API documentation for recommended and supported Speech API versions and models to ensure future compatibility.
gotcha The `client.tts.convert()` method now returns complete audio bytes directly, not an iterator of chunks. If your application expects chunk-by-chunk processing for real-time streaming or memory efficiency, you must use `client.tts.stream()` or `client.tts.stream_websocket()` instead.
Fix: For chunk-by-chunk processing, refactor your code to use `audio_stream = client.tts.stream(...)` and iterate over `audio_stream`. For real-time streaming, consider `client.tts.stream_websocket()`.
gotcha Automatic Speech Recognition (ASR) timestamps have changed from seconds to milliseconds in the newer SDK. This affects how you interpret and use timestamp data from ASR results.
Fix: If working with ASR timestamps, divide by 1000 to convert milliseconds back to seconds: `seconds = segment.start / 1000`.
gotcha API keys should be managed securely, preferably via environment variables (`FISH_API_KEY`). Committing API keys directly into source control is a security risk. The client automatically reads from `FISH_API_KEY` if available.
Fix: Set the `FISH_API_KEY` environment variable, or pass the key directly during client initialization (`client = FishAudio(api_key='your_key')`) but avoid hardcoding.

Install

pip install fish-audio-sdk Base Installation
pip install fish-audio-sdk[utils] With Audio Utilities (e.g., play, save)

Imports

FishAudio
wrong:
```
from fish_audio_sdk import Session
```
correct:
```
from fishaudio import FishAudio
```
For `fish-audio-sdk` versions 1.0.0 and above, the package installs the `fishaudio` module. The legacy `fish_audio_sdk` module was used in pre-1.0.0 versions and is deprecated.
AsyncFishAudio
```
from fishaudio import AsyncFishAudio
```
For asynchronous operations. Available in `fishaudio` module (installed by `fish-audio-sdk` >= 1.0.0).

Quickstart

This quickstart demonstrates how to initialize the Fish Audio client, synthesize text into speech, and save the resulting audio to a file. It is essential to set your `FISH_API_KEY` environment variable or pass it directly to the `FishAudio` client during initialization. The example uses the synchronous `convert` method for simplicity.

import os
from fishaudio import FishAudio
from fishaudio.utils import play, save

# Ensure your API key is set as an environment variable or pass it directly
# export FISH_API_KEY="YOUR_API_KEY_HERE"
api_key = os.environ.get('FISH_API_KEY', 'YOUR_API_KEY_HERE') # Replace with actual key or ensure env var is set

if api_key == 'YOUR_API_KEY_HERE':
    print("Warning: FISH_API_KEY environment variable not set. Using placeholder.")
    print("Please set FISH_API_KEY or provide it directly to FishAudio(api_key='...')")
    exit(1)

client = FishAudio(api_key=api_key)

text_to_synthesize = "Hello, this is a test from the Fish Audio Python SDK. Hope you enjoy it!"

try:
    # Generate speech (returns bytes)
    audio = client.tts.convert(text=text_to_synthesize)

    # Save the audio to a file
    output_filename = "output_audio.mp3"
    save(audio, output_filename)
    print(f"Audio saved to {output_filename}")

    # Optionally, play the audio (requires `utils` extra and platform support)
    # play(audio)
    # print("Audio played.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →