文本转语音接口

平台提供 AI Platform 兼容的文本转语音接口。是否可用取决于当前 API keys 的分组和模型目录： 先在 GET /v1/models 中确认存在可用的音频模型，再调用本接口。

请求

项目	值
方法	`POST`
路径	`/v1/audio/speech`
认证	`Authorization: Bearer <API_KEY>`
请求头	`Content-Type: application/json`
响应	二进制音频（不是 JSON）

返回的是二进制音频，不是 JSON —— 所以用 --output（或 -o）把响应直接写成文件。把它当 JSON 解析会得到一个空响应体。

voice 的可用取值取决于当前模型，不是所有模型都接受 alloy。

请求

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

请求参数

参数	类型	说明
`model`	string	必填。`GET /v1/models` 返回的音频模型 `data[].id`。
`input`	string	必填。要合成的文本。长度上限以实际模型为准。
`voice`	string	音色名称。可用音色取决于当前模型，请以模型详情为准。
`response_format`	string	输出音频格式，例如 `mp3`。支持的格式以实际模型为准。
`speed`	number	语速。是否支持及取值范围以实际模型为准。

音色、格式与语速的可用范围因模型而异。不要假设所有模型都支持 alloy 或 mp3，也不要把某个模型的音色列表写死在代码里。

响应

成功

成功响应的正文是二进制音频数据，不是 JSON。直接写入文件或流式转发给客户端即可。

# 保存为文件
curl ... --output speech.mp3

# 检查确实是音频而不是 JSON
file speech.mp3

失败

失败时返回带 error 对象的非 2xx 响应，结构与模型接口一致：

{
  "error": {
    "code": "invalid_parameter",
    "message": "..."
  }
}

常见的失败原因：

情况	表现	处理
分组里没有音频模型	`model_not_found` 或模型不可用	用 `GET /v1/models` 确认可用音频模型
音色不被该模型支持	`invalid_parameter`	改用该模型支持的音色
格式不被该模型支持	`invalid_parameter`	改用支持的 `response_format`
请求过于频繁	HTTP `429`	按提示退避重试

服务端接入建议

文本转语音是同步接口，响应即音频数据，接入时注意：

不要把它当 JSON 解析。先判断 HTTP 状态和 Content-Type，只有失败时才按 JSON 读取 error；
不要把音频直接透传给浏览器时忘记设置 Content-Type，否则浏览器会把它当文本处理；
控制 input 长度。超长文本建议在业务侧切分，分段合成后再拼接，避免单次请求超限；
音频文件建议转存到自己的存储，不要长期依赖平台返回的临时结果；
业务后端应缓存高频重复的合成结果，避免重复计费。

异步音频任务

除本同步接口外，平台还提供异步的音频生成能力（如配乐、音效）。这类任务的状态与制品在控制台「任务日志」中查询，处理方式与视频任务类似：创建后保存任务 ID，用查询接口轮询到终态，不要重复创建。

计费

音频接口的计费方式以模型广场的模型详情为准，可能按 Token、按次或按时长计费。计费与结算规则见计费与账单。

文本转语音接口

文本转语音接口

请求

请求参数

响应

成功

失败

服务端接入建议

异步音频任务

计费

相关文档

本页目录