离线任务 API参考-伶鹊(Cloud Contact Center)-阿里云帮助中心

异步语音合成接口通过「提交任务、获取结果」的方式完成长文本合成：提交后立即返回任务 ID，服务端在后台排队合成，客户端可主动查询任务状态或通过回调接收完成通知，并在合成完成后下载完整音频，适用于有声书制作、批量配音、音频素材预生成、超长文稿转语音等长文本场景。本文介绍通过 HTTP 请求访问 Voice Studio 异步语音合成服务的任务流程、接口地址和请求头。

线上地址

https://convai-platform.aliyuncs.com

1. 鉴权与请求头

1.1 必填请求头

Header	必填	说明
`Authorization`	是	`Bearer <api_key>`，鉴权凭证
`Content-Type`	是（POST 请求）	`application/json`

1.2 功能开关请求头

Header	必填	取值	说明
`X-TTS-TN`	否	`enable`	开启文本归一化。取值必须精确等于 `enable`（区分大小写），其余值或缺省即为关闭
`X-TTS-SSE`	否	`enable`	仅 SSE 流式合成使用，开启流式响应。不传或传其他值则走同步合成

2. 请求体

input object 必选

2.1 核心参数（均位于 `input`）

参数	位置	类型	必填	默认值	说明
`text`	`input`	string	是	-	合成文本。同步/SSE ≤ 2000 字符，异步任务 ≤ 100,000 字符
`voice`	`input`	string	是	-	音色 ID。系统音色或本账号可见的复刻音色

2.2 音频参数（均位于 `input`）

参数	类型	必填	默认值	取值范围	说明
`format`	string	否	`mp3`	`mp3` / `pcm` / `wav` / `opus`	音频编码格式。异步任务目前仅支持 mp3 / wav
`sample_rate`	int	否	`22050`	`8000` / `16000` / `22050` / `24000` / `44100` / `48000`	采样率（Hz）
`volume`	int	否	`50`	`[0, 100]`	音量
`rate`	float	否	`1.0`	`[0.5, 2.0]`	语速倍率
`pitch`	float	否	`1.0`	`[0.5, 2.0]`	音调倍率
`enable_ssml`	bool	否	`false`	-	开启 SSML 标记解析
`seed`	int	否	`0`	`[0, 65535]`	随机种子，相同 seed + 相同文本可复现合成结果
`word_timestamp_enabled`	bool	否	`false`	-	字级时间戳（仅 SSE 流式合成生效）

2.3 功能参数（均位于 `input`）

参数	类型	必填	默认值	取值 / 约束	说明
`enable_ssml`	Boolean	否	`false`	-	开启 SSML 标记解析。
`word_timestamp_enabled`	Boolean	否	`false`	-	字级时间戳（仅 SSE 流式合成返回）
`language_hints`	Array[String]	否	-	如 `["zh"]`	目标语言提示；当前引擎仅处理数组首元素，建议只传一个值
`seed`	Integer	否	-	`[0, 65535]`	随机种子。相同 seed + 相同文本可复现合成结果
`instruction`	String	否	-	≤ 2000 字符	指令控制（方言 / 情感 / 角色）。部分模型不支持
`hot_fix`	Object	否	-	`{"pronunciation": ..., "replace": ...}`	文本热修复（自定义发音 / 文本替换）。部分模型不支持
`enable_markdown_filter`	Boolean	否	`false`	-	合成前过滤 Markdown 标记。部分模型不支持
`enable_aigc_tag`	Boolean	否	`false`	-	在音频中嵌入 AIGC 隐性标识，配合 `aigc_propagator` / `aigc_propagate_id` 使用
`aigc_propagator`	String	否	-	-	AIGC 标识传播方
`aigc_propagate_id`	String	否	-	-	AIGC 标识传播 ID

3. 异步任务

适用于长文本或批量生产场景。提交任务后立即返回任务 ID，通过轮询或回调获取合成结果。

3.1 提交任务

请求

POST /v1/tts/tasks
Authorization: Bearer <api_key>
Content-Type: application/json

请求体

参数	位置	类型	必填	默认值	说明
`model`	顶层	string	是	-	合成模型
`input.*`	`input`	-	同上	-	合成参数（见第 4 节）；`input.text` ≤ 100,000 字符
`callback_url`	顶层	string	否	-	HTTPS 回调地址；任务完成时服务端主动通知（详见 7.4）

{
  "model": "cosyvoice-v2",
  "input": {
    "text": "（长文本，最大 100,000 字符...）",
    "voice": "longxiaochun_v2",
    "format": "mp3",
    "sample_rate": 22050,
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
  },
  "callback_url": "https://your-server.com/webhooks/tts"
}

响应（202 Accepted）

{
  "request_id": "req_x",
  "task_id": "task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d",
  "status": "PENDING"
}

字段	类型	说明
`request_id`	string	全链路请求 ID
`task_id`	string	任务 ID，后续查询 / 取消的凭据
`status`	string	初始固定 `PENDING`

限制

单用户排队中（PENDING）任务 ≤ 10，超出返回 429 RateLimitExceeded
input.text ≤ 100,000 字符

3.2 查询任务

请求

GET /v1/tts/tasks/{task_id}
Authorization: Bearer <api_key>

仅任务归属用户可查询，否则返回 404（不区分"不存在"与"无权限"，防探测）。

路径参数

参数	类型	说明
`task_id`	string	提交任务时返回的任务 ID

响应（200）

进行中（PENDING / RUNNING）

{
  "request_id": "req_y",
  "task_id": "task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d",
  "status": "RUNNING",
  "created_at": "2026-08-12T10:00:00Z"
}

成功（SUCCEEDED）

{
  "request_id": "req_y",
  "task_id": "task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d",
  "status": "SUCCEEDED",
  "output": {
    "audio": {
      "url": "https://oss-cn-hangzhou.aliyuncs.com/voice/tts/ws_xxx/task.mp3?Expires=1772698611&...",
      "expires_at": 1772698611
    }
  },
  "usage": {
    "characters": 98213
  },
  "created_at": "2026-08-12T10:00:00Z",
  "finished_at": "2026-08-12T10:03:12Z"
}

失败（FAILED）

{
  "request_id": "req_y",
  "task_id": "task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d",
  "status": "FAILED",
  "error": {
    "code": "EngineUnavailable",
    "message": "Engine unavailable: upstream timeout",
    "type": "server_error"
  },
  "created_at": "2026-08-12T10:00:00Z",
  "finished_at": "2026-08-12T10:02:30Z"
}

响应字段

字段	类型	出现条件	说明
`request_id`	string	恒有	全链路请求 ID
`task_id`	string	恒有	任务 ID
`status`	string	恒有	`PENDING` / `RUNNING` / `SUCCEEDED` / `FAILED` / `CANCELED`
`output.audio.url`	string	SUCCEEDED	24h 签名 URL；过期后再次查询将自动重签
`output.audio.expires_at`	int	SUCCEEDED	URL 过期时间
`usage.characters`	int	SUCCEEDED	计费字符数
`error.code`	string	FAILED	失败错误码
`error.message`	string	FAILED	失败描述
`error.type`	string	FAILED	`client_error` / `server_error`
`created_at`	string(ISO8601)	恒有	任务创建时间
`finished_at`	string(ISO8601)	终态	任务完成时间

3.3 取消任务

请求

GET  /v1/tts/tasks/cancel/{task_id}
POST /v1/tts/tasks/cancel/{task_id}
Authorization: Bearer <api_key>

同时支持 GET 和 POST 方法。仅支持取消 PENDING 状态的任务（尚未开始执行）。

响应

取消成功（200）

{
  "request_id": "req_z",
  "task_id": "task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d",
  "status": "CANCELED"
}

错误响应

HTTP 状态码	error.code	说明
401	`Unauthorized`	凭证无效 / 缺失
404	`NotFound`	任务不存在或非本人
409	`TaskNotCancelable`	任务已开始执行或已到达终态，无法取消

3.4 终态回调

提交任务时传入 callback_url，任务到达终态（SUCCEEDED / FAILED）时，服务端向该地址发起 GET 通知：

GET {callback_url}?taskId=task_9f2c...&status=SUCCEEDED&timestamp=1772698612000&taskType=tts_synthesis&success=true&signature=xxx

Query 参数	类型	说明
`taskId`	string	任务 ID
`status`	string	`SUCCEEDED` / `FAILED`
`timestamp`	int	回调时间戳（毫秒）
`taskType`	string	固定 `tts_synthesis`
`success`	bool	`true` / `false`
`signature`	string	签名：`Base64(MD5("taskId={taskId}&timestamp={timestamp}&userId={userId}"))`

回调规则：

回调端返回 2xx 视为成功
其余状态码 / 网络错误触发重试，最多 3 次（延迟 1min / 5min / 30min，指数退避）
callback_url 必须为 HTTPS 地址

3.5 完整请求示例

# 提交异步任务
curl -X POST https://convai-platform.aliyuncs.com/v1/tts/tasks \
  -H "Authorization: Bearer sk-9f2ac...d41b" \
  -H "Content-Type: application/json" \
  -H "X-TTS-TN: enable" \
  -d '{
    "model": "cosyvoice-v2",
    "input": {
      "text": "这是一段很长的文本...",
      "voice": "longxiaochun_v2",
      "format": "mp3"
    },
    "callback_url": "https://your-server.com/webhooks/tts"
  }'

# 查询任务状态
curl https://convai-platform.aliyuncs.com/v1/tts/tasks/task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d \
  -H "Authorization: Bearer sk-9f2ac...d41b"

# 取消任务（仅 PENDING，支持 GET / POST）
curl https://convai-platform.aliyuncs.com/v1/tts/tasks/cancel/task_9f2c8a1d-4b3e-4f5a-9c2d-1e6f8a7b3c4d \
  -H "Authorization: Bearer sk-9f2ac...d41b"

4. 错误码参考

4.1 错误码总表

error.code	HTTP 状态	error.type	说明
`InvalidParameter`	400	client_error	参数校验失败（含 voice 不存在、model 与音色不匹配、非法参数值）
`Unauthorized`	401	client_error	凭证无效 / 缺失 / 过期
`Forbidden`	403	client_error	音色 / 模型越权；音色审核未通过
`NotFound`	404	client_error	资源不存在或非本人（不区分，防探测）
`TextTooLong`	413	client_error	同步/SSE: > 2000 字符；异步任务: > 100,000 字符
`RateLimitExceeded`	429	client_error	QPM 限流 / 排队任务数已满
`TaskNotCancelable`	409	client_error	取消非 PENDING 状态任务
`InternalError`	500	server_error	服务内部错误
`EngineUnavailable`	503	server_error	上游合成引擎不可用 / 超时