文字转语音（同步）v2

HTTP TTS v2 仅用于维护现有客户端。新接入使用 HTTP TTS v3，因为 v3 提供严格字段合同、模型能力目录和可恢复的异步任务。

端点

POST /api/open/v2/speech/tts

完整地址：

https://fishaudio.org/api/open/v2/speech/tts

鉴权与请求头

Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json
X-Request-Id: YOUR_STABLE_REQUEST_ID

API Key 只能保存在服务端。成功响应为音频二进制，错误响应为 JSON。

请求

{
  "text": "你好，欢迎使用 Fish Audio。",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3",
  "speed": 1,
  "volume": 0,
  "stability": 1,
  "similarity": 1
}

字段	类型	必填	说明
`text`	string	是	1–10,000 字符
`voiceId`	string	是	公共或个人音色 ID
`modelId`	string	否	公共引擎模型 ID；省略时按音色和账户默认配置解析
`format`	string	否	`mp3`、`wav` 或 `ogg`，默认 `mp3`
`speed`	number	否	`0.5`–`2`，默认 `1`
`volume`	number	否	`-20`–`20`，默认 `0`
`pitch`	number	否	`-12`–`12`
`stability`	number	否	`0.5`–`1.5`
`similarity`	number	否	`0.5`–`1.5`
`language`	string	否	语言提示
`emotion`	string	否	全局情绪 ID
`instruction`	string	否	最多 1,600 字符的 Qwen 风格指令
`textNormalization`	boolean	否	结构化文本读音归一化

v2 还接受 engineModelId、version、qwenModel、minimaxEmotion 等历史字段。它们仅用于兼容旧客户端；新代码不要使用，也不要把它们和 v3 请求混用。v2 不提供供应商无关的能力目录。

curl 示例

curl "https://fishaudio.org/api/open/v2/speech/tts" \
  -H "Authorization: Bearer $FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: legacy-tts-001" \
  -d '{"text":"你好","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}' \
  --output speech.mp3

成功响应

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Request-Id: legacy-tts-001
X-OpenAPI-Quota-Remaining: 99994
X-OpenAPI-Credits-Used: 6

<binary audio data>

错误与重试

错误体使用扁平结构：

{
  "code": "ERR_REQUEST_ID_CONFLICT",
  "message": "Request id was reused with a different request",
  "requestId": "legacy-tts-001"
}

状态码	场景
`400`	请求、模型或音色组合无效
`401`	API Key 无效
`402`	API 额度不足
`409`	请求 ID 正在处理、已经完成或与不同参数冲突
`413`	HTTP 请求体超过上限
`429`	超过接口限流；遵循 `Retry-After`
`500`	生成或结算失败

只有重试完全相同的请求时才复用 X-Request-Id。同步响应丢失后不能重放音频；需要可靠恢复的业务应迁移到 v3 Jobs。

迁移到 v3

迁移时保留 text、voiceId 和通用控制参数，删除历史供应商字段，并显式传入能力目录返回的 modelId。完整步骤见迁移指南。