Skip to main content

python.png

Fish Audio Python SDK

PyPI version Python Version PyPI - Downloads codecov License

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()

Learn more

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"

Learn more

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)

Learn more

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
)

Learn more

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

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)

Source distribution for fish-audio-sdk 1.4.0
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)

Table of built distributions (wheels) for fish-audio-sdk 1.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page