> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fish Audio

> Real-time text-to-speech service using Fish Audio's WebSocket API

## Overview

`FishAudioTTSService` provides real-time text-to-speech synthesis through Fish Audio's WebSocket-based streaming API. The service offers custom voice models, prosody controls, and multiple audio formats optimized for conversational AI applications with low latency.

<CardGroup cols={2}>
  <Card title="Fish TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.fish.tts.html">
    Pipecat's API methods for Fish Audio TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-fish.py">
    Complete example with custom voice model
  </Card>

  <Card title="Fish Audio Documentation" icon="book" href="https://docs.fish.audio/developer-platform/getting-started/introduction">
    Official Fish Audio documentation
  </Card>

  <Card title="Voice Models" icon="microphone" href="https://fish.audio/app/my-voices/">
    Create and manage custom voice models
  </Card>
</CardGroup>

## Installation

To use Fish Audio services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[fish]"
```

## Prerequisites

### Fish Audio Account Setup

Before using Fish Audio TTS services, you need:

1. **Fish Audio Account**: Sign up at [Fish Audio Console](https://console.fish.audio/)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Models**: Create or select custom voice models for synthesis

### Required Environment Variables

* `FISH_API_KEY`: Your Fish Audio API key for authentication

## Configuration

### FishAudioTTSService

<ParamField path="api_key" type="str" required>
  Fish Audio API key for authentication.
</ParamField>

<ParamField path="reference_id" type="str" default="None" deprecated>
  Reference ID of the voice model to use for synthesis. Deprecated in v0.0.105.
  Use `settings=FishAudioTTSService.Settings(voice=...)` instead.
</ParamField>

<ParamField path="model_id" type="str" default="s2-pro" deprecated>
  Fish Audio TTS model to use.

  *Deprecated in v0.0.105. Use `settings=FishAudioTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="output_format" type="str" default="pcm">
  Audio output format. Options: `"pcm"`, `"opus"`, `"mp3"`, `"wav"`.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  Runtime-configurable voice settings. See [InputParams](#inputparams) below.

  *Deprecated in v0.0.105. Use `settings=FishAudioTTSService.Settings(...)` instead.*
</ParamField>

<ParamField path="settings" type="FishAudioTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `FishAudioTTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter        | Type              | Default     | Description                            |
| ---------------- | ----------------- | ----------- | -------------------------------------- |
| `model`          | `str`             | `None`      | Model identifier. *(Inherited.)*       |
| `voice`          | `str`             | `None`      | Voice identifier. *(Inherited.)*       |
| `language`       | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)* |
| `latency`        | `str`             | `NOT_GIVEN` | Latency mode setting.                  |
| `normalize`      | `bool`            | `NOT_GIVEN` | Whether to normalize audio.            |
| `temperature`    | `float`           | `NOT_GIVEN` | Temperature for sampling.              |
| `top_p`          | `float`           | `NOT_GIVEN` | Top-p sampling parameter.              |
| `prosody_speed`  | `float`           | `NOT_GIVEN` | Prosody speed control.                 |
| `prosody_volume` | `int`             | `NOT_GIVEN` | Prosody volume control.                |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.fish import FishAudioTTSService

tts = FishAudioTTSService(
    api_key=os.getenv("FISH_API_KEY"),
    settings=FishAudioTTSService.Settings(
        voice="your-voice-reference-id",
    ),
)
```

### With Prosody Controls

```python theme={null}
tts = FishAudioTTSService(
    api_key=os.getenv("FISH_API_KEY"),
    settings=FishAudioTTSService.Settings(
        voice="your-voice-reference-id",
        model="s2-pro",
        prosody_speed=1.2,
        prosody_volume=3,
        latency="balanced",
    ),
)
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **`voice` required**: You must specify either `voice` (preferred) or the deprecated `reference_id` parameter.
* **Model switching**: Changing the model or voice via settings automatically disconnects and reconnects the WebSocket with the new configuration.

## Event Handlers

Fish Audio TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                            |
| --------------------- | -------------------------------------- |
| `on_connected`        | Connected to Fish Audio WebSocket      |
| `on_disconnected`     | Disconnected from Fish Audio WebSocket |
| `on_connection_error` | WebSocket connection error occurred    |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Fish Audio")
```