Fish TTS API 對接說明

本接口基於 Fish Audio 官方 TTS API，僅在鑑權方式（使用本平台 token）和異步回調（callback_url 擴展）上有差異，請求體結構與上游一致。地址為 POST https://api.acedata.cloud/fish/tts。

申請流程

要使用 Fish TTS API，首先到 Ace Data Cloud 控制台獲取您的 API Token，留作備用。

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。 一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可在控制台充值通用餘額。

📘 完整文檔：Fish TTS API →

請求頭

Header	必填	說明
`authorization`	是	`Bearer {token}`，`{token}` 是在本平台申請的密鑰。
`content-type`	是	`application/json`。
`accept`	否	`application/json`。
`model`	否	TTS 模型，可選 `s1`、`s2-pro` 或 `s2.1-pro`，默認 `s2-pro`。`s2.1-pro` 為最新一代，`s2-pro` 表現力強；`s1` 更穩定，長文本不易跑偏。三者同價。

請求體字段

字段	類型	必填	說明
`text`	string	是	要合成的文本，非空字符串。
`format`	string	否	輸出音頻格式，可選 `mp3`（默認）、`wav`、`pcm`。`wav` 與 `pcm` 返回的都是 WAV 容器。`opus` 不受支持，傳入會直接返回 `400`。
`reference_id`	string \| string[]	否	克隆音色 ID（可由 Fish Model API 創建，或在 Fish Model Query 中檢索）。
`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 文檔。

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

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'

返回（實測）：

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url 指向本平台 CDN，可直接 GET 下載或在 <audio> 中播放。鏈接長期可用，但仍建議在你自己的存儲裡留一份。

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

下面用 Fish 平台上一個公開的西班牙語音色（_id 可通過 Fish Model Query 檢索得到）：

curl -X POST 'https://api.acedata.cloud/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"
  }'

返回（實測）：

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}

示例 3：調節語速 / 音量（`prosody`）

curl -X POST 'https://api.acedata.cloud/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"
  }'

返回（實測）：

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}

speed 大於 1 加快，小於 1 減慢；volume 單位 dB，0 表示不變，正數增益，負數衰減。

示例 4：切換模型 + 控制碼率

通過 HTTP 頭 model: s1 切換到穩定型模型，請求體中加 mp3_bitrate: 128 控制 MP3 码率：

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "高比特率 mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

返回（实测）：

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.mp3"
}

示例 5：PCM 原始波形

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

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "嗨",
    "format": "pcm",
    "sample_rate": 16000
  }'

返回（实测）：

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}

链接的扩展名跟随请求里的 format：mp3 得到 .mp3，wav 与 pcm 得到 .wav（WAV 容器，16 bit PCM）。

异步回调（`callback_url`）

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

curl -X POST 'https://api.acedata.cloud/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"
  }'

立即返回（实测）：

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

稍后 callback_url 会收到形如：

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}

也可以用 Fish Tasks API 主动按 task_id 拉取结果，详见该文档。

错误处理

400 token_mismatched：请求参数缺失或不合法（最常见是 text 为空，或 format 传了 mp3/wav/pcm 之外的值）。
401 invalid_token：鉴权 token 不存在或无效。
429 too_many_requests：触发账号速率限制。
500 api_error：服务器内部错误。

错误响应示例：

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "获取失败"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

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

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"输入应该是 'pcm' 或 'mp3'\",\"input\":\"wav\"}]"
}

结论

接入 Fish TTS 的最小代价是：在已有调用 api.fish.audio/v1/tts 的代码里把鉴权换成本平台 token，并在请求体里显式带上 format: "mp3"。长文本场景建议使用 callback_url 异步回调；对克隆音色 reference_id 的发现，请配合 Fish Model Query 与 Fish Model Get。

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

代理

進階

申請流程

請求頭

請求體字段

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

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

示例 3：調節語速 / 音量（`prosody`）

示例 4：切換模型 + 控制碼率

示例 5：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论

​申請流程

​請求頭

​請求體字段

​示例 1：最小請求（text + format=mp3）

​示例 2：使用克隆音色 reference_id

​示例 3：調節語速 / 音量（prosody）

​示例 4：切換模型 + 控制碼率

​示例 5：PCM 原始波形

​异步回调（callback_url）

​错误处理

​结论

申請流程

請求頭

請求體字段

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

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

示例 3：調節語速 / 音量（`prosody`）

示例 4：切換模型 + 控制碼率

示例 5：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论