文字转语音（同步）v1

同步 TTS 用于把一段文本立即转换为语音。它适合短文本试听、服务端即时配音、后台生成少量音频等场景。请求成功后，响应体是音频二进制，不是 JSON。

同步接口不新增独立的长文本硬限制。作为稳定性建议，超过约 2500 字、批量生成或需要可靠查询结果的场景，请使用文字转语音（异步），并根据文本长度和模型为 HTTP 客户端设置足够长的超时时间。

如果客户端要求使用 OpenAI /v1/audio/speech 请求格式，请改用 OpenAI 兼容 TTS 接口。

端点

POST /api/open/v1/speech/tts

完整地址：

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

鉴权与请求头

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

同步 TTS 是扣费接口。不要从浏览器端直接调用，以免泄露 API 密钥。

请求字段

{
  "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 字符；超过约 2500 字时建议使用异步接口
`voiceId`	string	是	音色 ID，可从 `GET /api/open/v1/voices` 获取
`modelId`	string	否	TTS 引擎模型 ID，例如 `fishaudio-s21pro-flash`
`format`	string	否	输出格式，例如 `mp3` 或 `wav`。可用值以 `GET /api/openapi.json` 返回的 schema 为准
`cache`	boolean	否	默认 `false` 返回音频二进制；`true` 返回包含临时音频 URL 的 JSON
`speed`	number	否	语速，范围 `0.5` 到 `2`，默认 `1`
`volume`	number	否	音量，范围 `-20` 到 `20`，默认 `0`
`stability`	number	否	稳定性，范围 `0.5` 到 `1.5`，默认 `1`，适用于 Fish Audio 模型
`similarity`	number	否	音色一致性，范围 `0.5` 到 `1.5`，默认 `1`，适用于 Fish Audio 模型
`pitch`	number	否	音调，范围 `-12` 到 `12`，默认 `0`，适用于 MiniMax 和 Qwen 模型
`language`	string	否	所选模型支持的语言提示
`emotion`	string	否	全局情绪 ID，可用值、默认行为与模型支持见全局情绪
`instruction`	string	否	Qwen Audio 3.0 的风格、方言、角色或情绪指令，最长 1600 字符
`textNormalization`	boolean	否	结构化文本读音归一化，默认开启

当前同步 TTS 请求字段保持精简：text、voiceId 是核心字段，modelId 用于指定 TTS 引擎模型，format 是可选输出格式。不要把其它站点或旧调试工具字段当作当前Open API 合同。

快速验证接口联通时，可以直接使用系统测试音色 00a1b221-6137-4b73-ad62-b0cbce134167；正式接入时再替换为目标音色 ID。

成功响应

成功时响应体是音频二进制：

HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-request-id: req_xxx

<binary audio data>

Content-Type 可能是 audio/mpeg 或 audio/wav，取决于服务端模型与响应格式。客户端应按响应头保存文件，而不是按 JSON 解析。

关键响应头：

响应头	说明
`x-request-id`	本次请求 ID，用于排查和支持定位

curl 示例

curl -X POST "https://fishaudio.org/api/open/v1/speech/tts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Request-Id: tts-order-123-segment-1" \
  -d '{
    "text": "你好，这是一段同步语音合成测试。",
    "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
    "modelId": "fishaudio-s21pro-flash",
    "format": "mp3",
    "speed": 1,
    "volume": 0,
    "stability": 1,
    "similarity": 1
  }' \
  --output output.mp3

错误行为

错误响应使用扁平结构：

{
  "code": "ERR_MISSING_REQUIRED_FIELDS",
  "message": "text and voiceId are required",
  "requestId": "req_xxx"
}

状态码	场景
`400`	JSON 无效、缺少 `text` / `voiceId`、格式不支持、`speed` 超出范围
`401`	API 密钥缺失或无效
`403`	当前账户无权访问指定能力、模型或音色
`402`	余额不足以覆盖本次同步生成
`409`	请求 ID 正在处理、已完成、已退款，或被用于不同参数
`405`	HTTP 方法不受支持；同步 TTS 仅接受 `POST`
`500`	服务端或供应商生成失败

由于成功响应是二进制，客户端应先判断 HTTP 状态码。只有非 2xx 错误才按 JSON 错误结构解析。路由层返回的 405 响应体可能为空，不应强制按 JSON 解析；请将请求方法改为 POST，并检查重定向是否改变了请求方法。

计费与积分

同步 TTS 成功时会产生扣费。需要查询生成后的余额时，调用 GET /api/open/v1/profile 读取当前账户额度。

X-Request-Id 是可选请求头，但强烈建议使用：每次逻辑生成创建一个稳定值，仅在重试完全相同的请求时复用，不要并发盲目重试。同一账户下：

相同请求仍在处理时返回 409 ERR_REQUEST_IN_PROGRESS，不会再次扣费；
同一请求 ID 携带不同参数时返回 409 ERR_REQUEST_ID_CONFLICT；
cache=true 的已完成请求会重放原有 URL JSON，不会再次扣费；
二进制响应已完成时返回 409 ERR_REQUEST_ALREADY_COMPLETED，因为服务端不会保存所有二进制响应；
已退款请求返回 409 ERR_REQUEST_PREVIOUSLY_REFUNDED，修正问题后请使用新的请求 ID。

如果请求在参数校验、鉴权或额度校验阶段失败，不会扣费。提供商、用量记录、缓存上传或短链创建失败时，本次预扣额度会立即退回。客户端超时不代表服务端已经停止；对重试敏感的同步请求建议设置 cache=true，超过约 2500 字则优先使用异步接口。