语音合成 API（TTS）​

New API 的语音合成走异步任务：提交合成请求拿到任务 ID，再轮询任务状态取回音频。 同一套接口还提供音色设计（用文字描述生成新音色）与官方音色列表。

本页字段、校验规则与状态码直接对应仓库实现，改动代码时请同步更新： relay/channel/task/ttscenter/models.go（请求/响应结构）、relay/channel/task/ttscenter/validation.go （校验规则与长度上限）、controller/tts.go（状态映射与响应组装）、router/tts-router.go（路由）。

端点一览​

鉴权与请求标识​

Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: your-unique-key-001

• Idempotency-Key 可选。同一个 key + 同一个请求体重复提交，只会创建一个任务，返回首次的任务 ID； 同一个 key 换成不同请求体会得到 409 IDEMPOTENCY_CONFLICT。不传时网关按本次请求自动生成。 key 最长 191 个字符。
• X-Request-Id 可选。不传时网关自动生成并在响应头回传，排查问题时带上它即可定位。

语音合成​

请求字段​

references[] 元素字段：

每个元素至少要有一个音频或图片来源，否则报 EMPTY_REFERENCE。 注意：stream_format 在异步任务接口上不支持，传了会报 STREAM_NOT_SUPPORTED。

请求示例​

curl -X POST 'https://api.yu-yu.ai/v1/audio/speech/tasks' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: speech-20260101-001' \
  -d '{
    "model": "volcengine",
    "input": "欢迎使用 New API 语音合成接口。",
    "voice": "zh_female_shuangkuaisisi_moon_bigtts",
    "response_format": "mp3",
    "speed": 1.0
  }'

音色设计​

用一段描述生成一个可复用的新音色。字段比语音合成多，且必填项更多：

curl -X POST 'https://api.yu-yu.ai/v1/voices/design/tasks' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "沉稳男声",
    "voice_slot_id": "slot-001",
    "prompt": "四十岁男性，声音低沉平稳，适合纪录片旁白",
    "preview_text": "这里是试听文本。",
    "language": "zh-CN"
  }'

提交响应​

两个提交端点的返回结构一致：

{
  "task_id": "task_xxxxxxxxxxxxxxxx",
  "task_type": "speech_generation",
  "status": 1,
  "status_text": "排队中",
  "progress": 0,
  "status_url": "/v1/tts/tasks/task_xxxxxxxxxxxxxxxx",
  "created_at": "2026-01-01T12:00:00"
}

查询任务​

curl 'https://api.yu-yu.ai/v1/tts/tasks/task_xxxxxxxxxxxxxxxx' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

响应在提交响应的字段基础上，补充了结果与时间信息：

状态码​

注意查询一个不存在的任务返回 HTTP 200，靠 status = -1 与 error.code = TASK_NOT_FOUND 判定， 不要只看状态码。

官方音色列表​

curl 'https://api.yu-yu.ai/v1/voices/official/all' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

返回官方可用音色集合（字段由语音服务提供，网关原样透传）。该端点不可用时返回 503，错误码 UPSTREAM_UNAVAILABLE。

轮询建议​

• 合成通常几秒到十几秒完成，建议首次延迟 2~3 秒、之后每 2 秒查询一次，上限 15 次左右。
• 命中 3 / 4 / 5 / -1 立即停止轮询。
• 用 Idempotency-Key + 失败重试可以安全重发，不会产生重复任务。

错误响应​

错误体形如：

{
  "error": {
    "message": "input is required",
    "type": "invalid_request_error",
    "param": "input",
    "code": "REQUIRED_FIELD_MISSING"
  }
}

常见问题​

• 合成成功但没找到音频地址：成功时结果字段由语音服务返回，名称以实际响应为准；也可以直接用 响应里的 status_url 配合本文档的查询端点复查。
• 音色设计报缺少 voice_slot_id：该字段必填，取值由你的业务侧约定（例如 slot-001）。
• 重复提交产生了两个任务：检查是否每次都传了不同的 Idempotency-Key；同一个 key 才会去重。
• 查询一直返回 1：任务在排队。语音服务并发有限，排队时间随并发量波动。

在线调试​