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

# Fish TTS API 对接说明

> Fish music generation 集成指南 - XHuoAPI

本接口基于 [Fish Audio 官方 TTS API](https://docs.fish.audio/text-to-speech/text-to-speech)，仅在鉴权方式（使用本平台 token）和异步回调（`callback_url` 扩展）上有差异，请求体结构与上游一致。地址为 `POST https://api.xhuoapi.ai/v1/fish/tts`。

## 申请流程

要使用 API，需要先到 [Fish TTS API](https://api.xhuoapi.ai/services/caf99abc-ddcf-4714-b2a5-862d9b469509) 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮。

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 API。

## 请求头

| Header          | 必填 | 说明                                                                     |
| --------------- | -- | ---------------------------------------------------------------------- |
| `authorization` | 是  | `Bearer {token}`，`{token}` 是在本平台申请的密钥。                                 |
| `content-type`  | 是  | `application/json`。                                                    |
| `accept`        | 否  | `application/json`。                                                    |
| `model`         | 否  | TTS 模型，可选 `s1` 或 `s2-pro`，默认 `s2-pro`。`s2-pro` 表现力更强；`s1` 更稳定，长文本不易跑偏。 |

## 请求体字段

| 字段             | 类型                  | 必填 | 说明                                                                                                                                                                                                       |
| -------------- | ------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`         | string              | 是  | 要合成的文本，非空字符串。                                                                                                                                                                                            |
| `format`       | string              | 是  | 输出音频格式。**当前必须显式传值**，可选 `mp3` 或 `pcm`。即使官方文档列出 `wav`、`opus`，本接口上游也会返回 `400 Input should be 'pcm' or 'mp3'`。                                                                                               |
| `reference_id` | string \| string\[] | 否  | 克隆音色 ID（可由 [Fish Model API](https://api.xhuoapi.ai/documents/62fdf4f1-6a05-4d92-bb15-1bf78b27a14a) 创建，或在 [Fish Model Query](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) 中检索）。 |
| `references`   | object\[]           | 否  | 内联参考样本，结构与上游一致，每项含 `audio` 与 `text`。与 `reference_id` 二选一。                                                                                                                                                |
| `sample_rate`  | integer             | 否  | 采样率，常用 `16000`、`22050`、`44100`。`format=mp3` 默认 44100。                                                                                                                                                    |
| `mp3_bitrate`  | integer             | 否  | MP3 码率，可选 `64`、`128`、`192`。仅 `format=mp3` 生效。                                                                                                                                                            |
| `prosody`      | object              | 否  | 韵律覆盖，支持 `speed`（语速，1.0 为原速）和 `volume`（音量增益 dB）。例如 `{"speed":1.2,"volume":0}`。                                                                                                                            |
| `chunk_length` | integer             | 否  | 上游分片长度，默认上游决定。                                                                                                                                                                                           |
| `temperature`  | number              | 否  | 采样温度，范围约 0.0–1.0。                                                                                                                                                                                        |
| `top_p`        | number              | 否  | top-p 采样参数。                                                                                                                                                                                              |
| `latency`      | string              | 否  | `normal` 或 `balanced`，缺省由本接口自动补 `normal`（直接传空字符串上游会拒绝）。                                                                                                                                                  |
| `normalize`    | boolean             | 否  | 是否对文本做归一化。                                                                                                                                                                                               |
| `callback_url` | string              | 否  | 异步回调地址，详见下文「异步回调」。**这是相对官方接口的扩展**。                                                                                                                                                                       |

> 字段命名与上游完全一致。除 `callback_url` 外，其余字段含义和取值参见 [Fish 官方 TTS 文档](https://docs.fish.audio/text-to-speech/text-to-speech)。

## 示例 1：最小请求（`text` + `format=mp3`）

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/05f81919f2e04e35bb404a88fb177854.mp3"
}
```

`audio_url` 是 Fish R2 直链，可直接 GET 下载或在 `<audio>` 中播放，签名通常在 1 小时内有效，建议落地后转存到自己的对象存储。

## 示例 2：使用克隆音色 `reference_id`

下面用 Fish 平台上一个公开的西班牙语音色（`_id` 可通过 [Fish Model Query](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) 检索得到）：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/560078cf603d4584a2313ca4cd742056.mp3"
}
```

## 示例 3：调节语速 / 音量（`prosody`）

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/f16759a3335748f1b4d1e56ed54d81dd.mp3"
}
```

`speed` 大于 1 加快，小于 1 减慢；`volume` 单位 dB，0 表示不变，正数增益，负数衰减。

## 示例 4：切换模型 + 控制码率

通过 HTTP 头 `model: s1` 切换到稳定型模型，请求体中加 `mp3_bitrate: 128` 控制 MP3 码率：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/6b660348776e40529e537aa30b1051d2.mp3"
}
```

## 示例 5：PCM 原始波形

需要在浏览器里做实时拼接、或在客户端做后续处理（混音、变速）的场景，推荐使用 `pcm`：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/2052cc1f33b049d99a18fcc496f4462e.mp3"
}
```

> 当前响应链接的扩展名固定为 `.mp3`，实际内容为请求中指定 `format` 的字节流。下载时应根据请求里的 `format` 决定如何解析。

## 异步回调（`callback_url`）

长文本一次合成可能需要十几秒到几十秒，连接如果中断需要重试。请求体中传 `callback_url` 后，接口会立即返回 `{task_id, started_at}`，上游真正完成时把完整结果以 POST JSON 形式回调到该 URL，请求体中带同一个 `task_id`。

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'
```

立即返回（实测）：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": "2026-05-11T01:23:04.742Z"
}
```

稍后 `callback_url` 会收到形如：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

也可以用 [Fish Tasks API](https://api.xhuoapi.ai/documents/fc541fac-a941-47fd-b6f7-48d6cb9da523) 主动按 `task_id` 拉取结果，详见该文档。

## 错误处理

* `400 token_mismatched`：请求参数缺失或不合法（最常见是漏传 `format`、`text` 为空）。
* `401 invalid_token`：鉴权 token 不存在或无效。
* `429 too_many_requests`：触发账号速率限制。
* `500 api_error`：服务器内部错误。

错误响应示例：

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

参数校验错误会把上游的 pydantic 报错原文放在 `message` 字段，便于定位是哪个字段不合法，例如：

```json theme={null}
{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}
```

## 结论

接入 Fish TTS 的最小代价是：在已有调用 `api.fish.audio/v1/tts` 的代码里把鉴权换成本平台 token，并在请求体里**显式带上** `format: "mp3"`。长文本场景建议使用 `callback_url` 异步回调；对克隆音色 `reference_id` 的发现，请配合 [Fish Model Query](https://api.xhuoapi.ai/documents/5a9b3e03-2896-5606-a6b9-d9f4469f0e9d) 与 [Fish Model Get](https://api.xhuoapi.ai/documents/dabdffe7-254b-5a3f-9eca-425d614d82b9)。