Fish Audio Python SDK
The official Python library for the Fish Audio API
Documentation: Python SDK Guide | API Reference
Installation
pip install fish-audio-sdk
# With audio playback utilities
pip install fish-audio-sdk[utils]
Authentication
Get your API key from fish.audio/app/api-keys:
export FISH_API_KEY=your_api_key_here
Or provide directly:
from fishaudio import FishAudio
client = FishAudio(api_key="your_api_key")
Quick Start
Synchronous:
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:
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())
Core Features
Text-to-Speech
Selecting a model:
# Recommended for production
production_audio = client.tts.convert(
text="Production speech",
model="s2.1-pro",
)
# Free to use, including on a new account with no API credit
free_audio = client.tts.convert(
text="Free speech",
model="s2.1-pro-free",
)
# Drama 3: our most expressive model (uses API credit)
drama_audio = client.tts.convert(
text="Expressive speech",
model="drama-3",
)
With custom voice:
# Use a specific voice by ID
audio = client.tts.convert(
text="Custom voice",
reference_id="802e3bc2b27e49c2995d23ef70e6ac89"
)
With speed control:
audio = client.tts.convert(
text="Speaking faster!",
speed=1.5 # 1.5x speed
)
Reusable configuration:
from fishaudio.types import TTSConfig, Prosody
config = TTSConfig(
prosody=Prosody(speed=1.2, volume=-5),
reference_id="933563129e564b19a115bedd57b7406a",
format="wav",
latency="balanced"
)
# Reuse across generations
audio1 = client.tts.convert(text="First message", config=config)
audio2 = client.tts.convert(text="Second message", config=config)
Chunk-by-chunk processing:
# Stream and process chunks as they arrive
for chunk in client.tts.stream(text="Long content..."):
send_to_websocket(chunk)
# Or collect all chunks
audio = client.tts.stream(text="Hello!").collect()
Speech-to-Text
from fishaudio.core import RequestOptions
# transcribe-1-pro is the recommended model. Select it with the model header;
# without it, the request runs on transcribe-1.
pro = RequestOptions(additional_headers={"model": "transcribe-1-pro"})
with open("meeting.wav", "rb") as f:
result = client.asr.transcribe(audio=f.read(), request_options=pro)
# On transcribe-1-pro, text keeps <|speaker:N|> markers; speaker_turns has clean text per speaker.
print(result.text)
# Word-level timestamps
for segment in result.segments:
print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")
# Speaker turns (transcribe-1-pro, returned with timestamps)
for turn in result.speaker_turns or []:
print(f"[{turn.start:.2f}s - {turn.end:.2f}s] {turn.speaker}: {turn.text}")
# Language of the transcript, when the API returns it
print(result.language_code) # e.g. "en"
Real-time Streaming
Stream dynamically generated text for conversational AI and live applications:
Synchronous:
def text_chunks():
yield "Hello, "
yield "this is "
yield "streaming!"
audio_stream = client.tts.stream_websocket(text_chunks(), latency="balanced")
play(audio_stream)
Asynchronous:
async def text_chunks():
yield "Hello, "
yield "this is "
yield "streaming!"
audio_stream = await client.tts.stream_websocket(text_chunks(), latency="balanced")
play(audio_stream)
Voice Cloning
Instant cloning:
from fishaudio.types import ReferenceAudio
# Clone voice on-the-fly
with open("reference.wav", "rb") as f:
audio = client.tts.convert(
text="Cloned voice speaking",
references=[ReferenceAudio(
audio=f.read(),
text="Text spoken in reference"
)]
)
Persistent voice models:
# Create voice model for reuse
with open("voice_sample.wav", "rb") as f:
voice = client.voices.create(
title="My Voice",
voices=[f.read()],
description="Custom voice clone"
)
# Use the created model
audio = client.tts.convert(
text="Using my saved voice",
reference_id=voice.id
)
Resource Clients
| Resource | Description | Key Methods |
|---|---|---|
client.tts |
Text-to-speech | convert(), stream(), stream_websocket() |
client.asr |
Speech recognition | transcribe() |
client.voices |
Voice management | list(), get(), create(), update(), delete() |
client.account |
Account info | get_credits(), get_package() |
Error Handling
from fishaudio.exceptions import (
AuthenticationError,
RateLimitError,
ValidationError,
FishAudioError
)
try:
audio = client.tts.convert(text="Hello!")
except AuthenticationError:
print("Invalid API key")
except RateLimitError:
print("Rate limit exceeded")
except ValidationError as e:
print(f"Invalid request: {e}")
except FishAudioError as e:
print(f"API error: {e}")
Resources
- Documentation: SDK Guide | API Reference
- Package: PyPI | GitHub
- Legacy SDK: Documentation | Migration Guide
License
This project is licensed under the Apache-2.0 License - see the LICENSE file for details.
Metadata
Release files for fish-audio-sdk 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fish_audio_sdk-1.4.0.tar.gz | 1.1 MB | With provenance | Details for fish_audio_sdk-1.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fish_audio_sdk-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for fish_audio_sdk-1.4.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / fish_audio_sdk-1.4.0.tar.gz
| Download URL | fish_audio_sdk-1.4.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
063e0eb2b193d9ae626d1bc7ac099899eb7cf009a46b0317222db720206855fe
|
|
BLAKE2b-256 checksum How to use checksums |
00564045f59a486cdb86f5a546c062818851dfd9c876d0673f5322f8c084a435
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / fish_audio_sdk-1.4.0-py3-none-any.whl
| Download URL | fish_audio_sdk-1.4.0-py3-none-any.whl |
|---|---|
| Size | 44.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a17a47cffe9941a198aba679fa2fa9fe0ea75e90377e7b20afd35cf2f8ffd70
|
|
BLAKE2b-256 checksum How to use checksums |
bf371b257ddee4cbf16b5003326dd032316110ae0ef5daff845aeb02b4edfc0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for fish-audio-sdk 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fish_audio_sdk-1.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.