文字转语音（同步）

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

长文本、批量生成或需要轮询状态的场景，请使用文字转语音（异步）。

端点

POST /api/open/v1/speech/tts

完整地址：

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

鉴权与请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

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

请求字段

{
  "text": "你好，这是一段 Fish Audio 语音合成测试。",
  "voiceId": "clara",
  "format": "mp3",
  "speed": 1,
  "emotion": "calm"
}

字段	类型	必填	说明
`text`	string	是	待合成文本，最短 1 字符，最长 5000 字符
`voiceId`	string	是	音色 ID，可从 `GET /api/open/v1/voices` 获取
`format`	string	否	输出格式，例如 `mp3` 或 `wav`。可用值以 `GET /api/openapi.json` 返回的 schema 为准
`speed`	number	否	语速，范围 `0.5` 到 `2`，默认 `1`
`emotion`	string	否	情绪 ID。可用值以 OpenAPI schema 中的枚举为准

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

成功响应

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

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" \
  -d '{
    "text": "你好，这是一段同步语音合成测试。",
    "voiceId": "clara",
    "format": "mp3",
    "speed": 1,
    "emotion": "calm"
  }' \
  --output output.mp3

错误行为

错误响应使用嵌套结构：

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

状态码	场景
`400`	JSON 无效、缺少 `text` / `voiceId`、格式不支持、`speed` 超出范围
`401`	API 密钥缺失或无效
`403`	当前账户无权访问指定能力、模型或音色
`402`	余额不足以覆盖本次同步生成
`500`	服务端或供应商生成失败

由于成功响应是二进制，客户端应先判断 HTTP 状态码。只有非 2xx 错误才按 JSON 错误结构解析。

计费与积分

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

如果请求在参数校验、鉴权或额度校验阶段失败，不会返回可用音频。对 500 可以做有限次数退避重试，但要注意重复请求可能生成多份音频并产生多次扣费。

文字转语音（同步）

本页内容