Install & Compatibility
Where this runs
tested against v1.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.999s · 33.5MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 5.2s · import 0.923s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FishAudio
✓ from fishaudio import FishAudio
✗ from fish_audio_sdk import Session
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).
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}")
Debug
Known issues
breakingMigration 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.fixEnsure `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`.
affects: <1.0.0 (legacy module) to >=1.0.0 (new module)
deprecatedSpeech 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.fixConsult the latest Fish Audio API documentation for recommended and supported Speech API versions and models to ensure future compatibility.
affects: 1.3.0 and higher
gotchaThe `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.fixFor 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()`.
affects: 1.0.0 and higher
gotchaAutomatic 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.fixIf working with ASR timestamps, divide by 1000 to convert milliseconds back to seconds: `seconds = segment.start / 1000`.
affects: 1.0.0 and higher
gotchaAPI 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.fixSet the `FISH_API_KEY` environment variable, or pass the key directly during client initialization (`client = FishAudio(api_key='your_key')`) but avoid hardcoding.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fishaudio'
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.
fixEnsure `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.
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.
fixIf 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)
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.
fixAvoid 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`.
Upgrade
Version history
1.3.0latest on PyPI · released Mar 10, 2026
Audit
Dependencies
No dependency data recorded yet.