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

# Fish Audio Configuration

> Configure Fish Audio voices and models with an Anam avatar in LiveKit, use your own Fish Audio API key, deploy the agent, and fix common problems.

## Installation

```bash theme={"system"}
uv add "livekit-agents[anam,silero]==1.8.12" "python-dotenv==1.2.4"
```

The `anam` extra installs the Anam avatar plugin. LiveKit Agents 1.8.9 or later is required for `fishaudio/drama-3`. Add the `fishaudio` extra only if you [use your own Fish Audio API key](#use-your-own-fish-audio-api-key).

## Environment variables

| Variable | Required | Description |
| - | - | - |
| `LIVEKIT_URL` | Yes | Your LiveKit Cloud project URL (`wss://...`). It must be reachable by Anam's servers, so don't use a local LiveKit server. |
| `LIVEKIT_API_KEY` | Yes | LiveKit project API key. Also authenticates LiveKit Inference. |
| `LIVEKIT_API_SECRET` | Yes | LiveKit project API secret. |
| `ANAM_API_KEY` | Yes | Anam API key from [Anam Lab](https://lab.anam.ai/api-keys). |
| `ANAM_AVATAR_ID` | Yes | The avatar's appearance. |
| `FISH_API_KEY` | Plugin only | Fish Audio API key, for the [Fish Audio plugin](#use-your-own-fish-audio-api-key). |

Keep these in server configuration. Never put them in browser code or `NEXT_PUBLIC_` variables.

## Fish Audio voice

With LiveKit Inference, set the [Fish Audio](https://fish.audio/?utm_source=anam\&utm_medium=referral) model and voice on `inference.TTS`:

```python theme={"system"}
from livekit.agents import inference

tts = inference.TTS(
    model="fishaudio/drama-3",
    voice="536d3a5e000945adb7038665781a4aca",  # Ethan
    language="en",
)
```

| Model ID | Notes |
| - | - |
| `fishaudio/drama-3` | [Drama 3](https://fish.audio/drama-3/?utm_source=anam\&utm_medium=referral), used by the demo and Quickstart |
| `fishaudio/s2.1-pro` | |
| `fishaudio/s2-pro` | |

All three models support `en`, `zh`, `ja`, `de`, `fr`, `es`, `ko`, `ar`, `ru`, `nl`, `it`, `pl`, and `pt`. Choose a voice from [LiveKit's Fish Audio voice list](https://docs.livekit.io/agents/models/tts/fishaudio/#voices). Pre-existing custom or community Fish Audio voices aren't available through Inference; use the [plugin](#use-your-own-fish-audio-api-key) for those.

### Fish Audio options

Pass Fish Audio parameters through `extra_kwargs`:

```python theme={"system"}
tts = inference.TTS(
    model="fishaudio/drama-3",
    voice="536d3a5e000945adb7038665781a4aca",
    language="en",
    extra_kwargs={
        "latency": "low",
        "speed": 1.1,
        "temperature": 0.7,
    },
)
```

| Parameter | Default | Description |
| - | - | - |
| `latency` | `"balanced"` | `"normal"` for best quality, `"balanced"`, or `"low"` for lowest latency |
| `speed` | `1.0` | Speaking rate, from `0.5` to `2.0` |
| `volume` | `0.0` | Volume adjustment in dB |
| `temperature` | `0.7` | Variation in delivery, from `0.0` to `1.0` |
| `top_p` | `0.7` | Nucleus sampling, from `0.0` to `1.0` |
| `normalize` | `True` | Normalize numbers, dates, and currency (English and Chinese) |

See [LiveKit's Fish Audio model parameters](https://docs.livekit.io/agents/models/tts/fishaudio/) for the full list.

## Speech-to-text (STT) and large language model (LLM)

The Quickstart uses `inference.STT(model="auto", language="en")`, which lets LiveKit Inference pick the best STT model for the language, and `inference.LLM(model="openai/gpt-oss-120b")`. Any LiveKit Inference [STT](https://docs.livekit.io/agents/models/stt/) or [LLM](https://docs.livekit.io/agents/models/llm/) model works without extra API keys. When adding the avatar to an existing agent, keep your current STT, LLM, tools, and instructions.

## Avatar

```python theme={"system"}
from livekit.plugins import anam

avatar = anam.AvatarSession(
    persona_config=anam.PersonaConfig(
        name="Fish Audio avatar",
        avatarId=os.environ["ANAM_AVATAR_ID"],
        avatarModel="cara-4.1-express",
    ),
    api_key=os.environ["ANAM_API_KEY"],
)

await avatar.start(session, room=ctx.room)
await session.start(room=ctx.room, agent=agent)
```

Start the avatar before `session.start()` so all speech goes through Anam from the first greeting. For Director Notes, custom participant identities, and other avatar options, see [LiveKit configuration](https://anam.ai/docs/integrations/livekit/configuration.md).

## Use your own Fish Audio API key

Use the [Fish Audio plugin](https://docs.fish.audio/developer-guide/integrations/livekit?utm_source=anam\&utm_medium=referral) to bill [Fish Audio](https://fish.audio/?utm_source=anam\&utm_medium=referral) directly or to use custom and community voices:

```bash theme={"system"}
uv add "livekit-agents[anam,fishaudio,silero]==1.8.12"
```

Add `FISH_API_KEY` to `.env.local`, then replace the `tts` setting:

```python theme={"system"}
from livekit.plugins import fishaudio

tts = fishaudio.TTS(
    model="drama-3",
    voice_id="your_fish_audio_voice_id",
)
```

`voice_id` is the voice's reference ID in Fish Audio, not your Anam avatar ID. The plugin also provides Fish Audio speech-to-text:

```python theme={"system"}
stt = fishaudio.STT(model="transcribe-stream-1")
```

See [Fish Audio's LiveKit guide](https://docs.fish.audio/developer-guide/integrations/livekit?utm_source=anam\&utm_medium=referral) and [LiveKit's Fish Audio plugin reference](https://docs.livekit.io/agents/models/tts/fishaudio/#plugin) for every option.

## Running your agent

> [tab] Development
>
> ```bash theme={"system"}
> uv run -m livekit.agents download-files
> lk agent dev --deployment production agent.py
> ```
>
> `lk agent dev` (LiveKit CLI v2.19 or later) reloads on file changes. By default it registers under a random `dev-` [deployment](https://docs.livekit.io/deploy/agents/deployments/), which a frontend dispatching by agent name can't reach. `--deployment production` makes your local worker receive those dispatches. In a project where a deployed agent with the same name serves real users, leave the flag off and use the Agent Console link that `lk agent dev` prints.

> [tab] Production
>
> ```bash theme={"system"}
> lk agent create
> ```
>
> Creates the agent in LiveKit Cloud from your project directory, then `lk agent deploy` ships later versions. Set `ANAM_API_KEY` and `ANAM_AVATAR_ID` as agent secrets. See [LiveKit's deployment guide](https://docs.livekit.io/deploy/agents/) for details.

## Troubleshooting

> [accordion] The frontend connects but the agent never joins
>
> * Match `AGENT_NAME` in the frontend to `agent_name` in `agent.py`
> * Use the same LiveKit project for the agent and the frontend
> * Start the local worker with `--deployment production`; a `dev-` deployment doesn't receive dispatches that don't name one
> * See [agent dispatch](https://docs.livekit.io/agents/server/agent-dispatch/)

> [accordion] The voice is wrong or Fish Audio requests fail
>
> * Check that LiveKit Inference and billing are enabled for your project
> * Confirm that the model and voice are supported by Inference
> * For the plugin, confirm that `FISH_API_KEY` can access the voice and your Fish Audio account has credit
> * Read the provider error in the agent logs

> [accordion] Audio plays but the avatar is missing
>
> * Check `ANAM_API_KEY` and `ANAM_AVATAR_ID`
> * Confirm that `avatar.start()` succeeds before `session.start()`
> * Make sure your frontend renders the avatar participant's video track
> * Replace local LiveKit URLs such as `ws://localhost:7880` with a publicly reachable endpoint

> [accordion] The agent doesn't respond to the microphone
>
> * Allow microphone access in the browser
> * Confirm that the visitor publishes audio and that `participant_identity` points at the visitor, not the avatar
> * Check the agent logs for STT or LLM errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.