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

# Fish Audio TTS provider

> Configure Fish Audio as a text-to-speech provider on Telnyx with curated voices, cross-lingual synthesis, and multiple audio formats and sample rates.

**Voice format:** `FishAudio.<Model>.<VoiceId>`

Fish Audio is a Telnyx-hosted external TTS provider. Telnyx exposes a **hand-vetted shortlist** of Fish Audio voices from their public Voice Library.

<Info>
  Fish Audio is **cross-lingual** — any voice can speak any language from the input text. The `language` field in the voice listing is the voice's native accent only, not a synthesis constraint.
</Info>

## Models

| Model      | Description                                                                |
| ---------- | -------------------------------------------------------------------------- |
| `s2.1-pro` | Latest generation. Improved quality, latency, and throughput. **Default.** |
| `s2-pro`   | Previous generation. Multi-speaker, expression control.                    |
| `s1`       | Oldest generation.                                                         |

All curated voices are available under all three models.

## Curated Voices

| Voice  | Gender | Native Language | Voice ID                           | Sample                                                                  |
| ------ | ------ | --------------- | ---------------------------------- | ----------------------------------------------------------------------- |
| Aria   | Female | English         | `933563129e564b19a115bedd57b7406a` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-aria.mp3" />   |
| Nova   | Female | English         | `b545c585f631496c914815291da4e893` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-nova.mp3" />   |
| Paula  | Female | English         | `c2623f0c075b4492ac367989aee1576f` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-paula.mp3" />  |
| Claire | Female | French          | `5567200c7d8341738f0892bbacd3be3c` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-claire.mp3" /> |
| Yuki   | Female | Japanese        | `5161d41404314212af1254556477c17d` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-yuki.mp3" />   |
| Ethan  | Male   | English         | `536d3a5e000945adb7038665781a4aca` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-ethan.mp3" />  |
| Atlas  | Male   | English         | `c5f56a6cc2ec4fa8920cb4c5889a3fb7` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-atlas.mp3" />  |
| Max    | Male   | English         | `802e3bc2b27e49c2995d23ef70e6ac89` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-max.mp3" />    |
| Adrian | Male   | English         | `bf322df2096a46f18c579d0baa36f41d` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-adrian.mp3" /> |
| Mateo  | Male   | Spanish         | `35199d5438854f5d9157c500479ab684` | <audio controls src="/audio/tts-samples/telnyx-fishaudio-mateo.mp3" />  |

<Warning>
  Only curated catalog voices are accepted for synthesis. Arbitrary Fish Voice-Library `reference_id`s cannot be used under the Telnyx API key.
</Warning>

## Emotion Tags

Fish Audio S2 models (`s2.1-pro`, `s2-pro`) support inline emotion, tone, and audio-effect markers placed directly in the input text. S1 uses parentheses — `(happy)` — instead of brackets. The markers are processed by the upstream Fish Audio API and do not add latency or count toward token limits.

```text theme={null} theme={null}
[happy] What a beautiful day!
[sad] I'm sorry to hear that.
[excited] This is amazing news!
[whispering] I have a secret to share.
[laughing] That was hilarious! Ha, ha!
```

The same syntax works on both the REST endpoint and the WebSocket `text` field. Markers can be combined for layered effects — `[excited][laughing] We won! Ha ha!` — and accept intensity modifiers like `[slightly sad]`, `[very excited]`, `[extremely angry]`.

For the full list of supported emotions, tone markers, audio effects, and S1 syntax, see Fish Audio's [Emotion Control guide](https://docs.fish.audio/developer-guide/core-features/emotions).

***

## WebSocket

### Query Parameters

| Parameter      | Type    | Default    | Description                             |
| -------------- | ------- | ---------- | --------------------------------------- |
| `audio_format` | string  | `linear16` | `mp3`, `wav`, `linear16` (maps to PCM). |
| `sample_rate`  | integer | `24000`    | Depends on format (see table below).    |

### Voice Settings

Fish Audio does not expose speed or pitch controls. `voice_settings` are limited to format and sample rate overrides. Emotion and tone are controlled inline in the text via bracket markers — see [Emotion Tags](#emotion-tags) below.

| Field         | Type    | Default | Description                                        |
| ------------- | ------- | ------- | -------------------------------------------------- |
| `format`      | string  | `pcm`   | `mp3`, `wav`, `pcm`, `opus`.                       |
| `sample_rate` | integer | `24000` | Sample rate in Hz (valid values depend on format). |

```json theme={null}
{
  "text": " ",
  "voice_settings": {
    "format": "mp3",
    "sample_rate": 44100
  }
}
```

## REST API

### Fields

| Field         | Type    | Default         | Description                                        |
| ------------- | ------- | --------------- | -------------------------------------------------- |
| `format`      | string  | `pcm`           | `mp3`, `wav`, `pcm`, `opus`.                       |
| `sample_rate` | integer | `24000`         | Sample rate in Hz (valid values depend on format). |
| `output_type` | string  | `binary_output` | `binary_output`, `base64_output`, or `audio_id`.   |

### Response

Default (`binary_output`): chunked audio bytes.

With `output_type: "base64_output"`: JSON with base64-encoded audio.

With `output_type: "audio_id"`: JSON with an `audio_url` for deferred retrieval.

## Audio Formats & Sample Rates

Each format has a fixed set of accepted sample rates:

| Format | Accepted Sample Rates (Hz)       |
| ------ | -------------------------------- |
| `pcm`  | 8000, 16000, 24000, 32000, 44100 |
| `wav`  | 8000, 16000, 24000, 32000, 44100 |
| `mp3`  | 32000, 44100                     |
| `opus` | 48000                            |

<Info>
  On WebSocket, the `audio_format` query parameter and `voice_settings.format` are independent parameters with different vocabularies. The `audio_format` query param accepts `mp3`, `wav`, and `linear16` (which maps to `pcm`). The `voice_settings.format` field accepts `mp3`, `wav`, `pcm`, and `opus` directly. If both are set, `voice_settings.format` takes precedence.
</Info>

## In-Call Playback

Fish Audio is available for in-call TTS via Call Control `speak` and TeXML `<Say>`. For telephony playback, the gateway automatically delivers MP3 at 44.1 kHz to ensure correct resampling by the call-control audio pipeline.

See [In-Call Playback](/docs/voice/tts/in-call-playback) for details.

## Provider Docs

* [Fish Audio API Reference](https://docs.fish.audio/api-reference/endpoint/openapi-v1/text-to-speech)
* [Fish Audio Voice Library](https://fish.audio/)