{"id":8163,"library":"fish-audio-sdk","title":"Fish Audio Python SDK","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/fishaudio/fish-audio-python","tags":["audio","tts","speech-synthesis","api-client","voice-cloning","asr"],"install":[{"cmd":"pip install fish-audio-sdk","lang":"bash","label":"Base Installation"},{"cmd":"pip install fish-audio-sdk[utils]","lang":"bash","label":"With Audio Utilities (e.g., play, save)"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from fish_audio_sdk import Session","symbol":"FishAudio","correct":"from fishaudio import FishAudio"},{"note":"For asynchronous operations. Available in `fishaudio` module (installed by `fish-audio-sdk` >= 1.0.0).","symbol":"AsyncFishAudio","correct":"from fishaudio import AsyncFishAudio"}],"quickstart":{"code":"import os\nfrom fishaudio import FishAudio\nfrom fishaudio.utils import play, save\n\n# Ensure your API key is set as an environment variable or pass it directly\n# export FISH_API_KEY=\"YOUR_API_KEY_HERE\"\napi_key = os.environ.get('FISH_API_KEY', 'YOUR_API_KEY_HERE') # Replace with actual key or ensure env var is set\n\nif api_key == 'YOUR_API_KEY_HERE':\n    print(\"Warning: FISH_API_KEY environment variable not set. Using placeholder.\")\n    print(\"Please set FISH_API_KEY or provide it directly to FishAudio(api_key='...')\")\n    exit(1)\n\nclient = FishAudio(api_key=api_key)\n\ntext_to_synthesize = \"Hello, this is a test from the Fish Audio Python SDK. Hope you enjoy it!\"\n\ntry:\n    # Generate speech (returns bytes)\n    audio = client.tts.convert(text=text_to_synthesize)\n\n    # Save the audio to a file\n    output_filename = \"output_audio.mp3\"\n    save(audio, output_filename)\n    print(f\"Audio saved to {output_filename}\")\n\n    # Optionally, play the audio (requires `utils` extra and platform support)\n    # play(audio)\n    # print(\"Audio played.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (legacy module) to >=1.0.0 (new module)"},{"fix":"Consult the latest Fish Audio API documentation for recommended and supported Speech API versions and models to ensure future compatibility.","message":"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.","severity":"deprecated","affected_versions":"1.3.0 and higher"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"1.0.0 and higher"},{"fix":"If working with ASR timestamps, divide by 1000 to convert milliseconds back to seconds: `seconds = segment.start / 1000`.","message":"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.","severity":"gotcha","affected_versions":"1.0.0 and higher"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'fishaudio'"},{"fix":"If you require audio chunks, switch from `client.tts.convert()` to `client.tts.stream()` or `client.tts.stream_websocket()`.","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.","error":"Code expects TTS chunks but gets complete audio."},{"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`.","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.","error":"Because fish-audio-sdk==2025.6.3 was yanked (reason: Break Change)"}]}