非实时语音合成 HTTP/SSE API参考-伶鹊(Cloud Contact Center)-阿里云帮助中心

语音合成接口通过一次 HTTP 请求将文本转为语音，支持整段返回与逐句流式返回两种方式：整段返回一次拿到完整音频文件，流式返回可在首句合成完成后立即播放，适用于操作提示音、网页试听、对话回复播报、短篇文案朗读等短文本场景。本文介绍通过 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. 同步合成

3.1 请求

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

适用：短文本（≤ 2000 字符），一次请求一次响应，返回音频下载地址。

3.2 请求体

见第 2 节。

3.3 响应（200）

{
  "request_id": "ee88b03d-7a4c-4e1f-9b2d-3c5f8e9a1d04",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "url": "https://oss-cn-hangzhou.aliyuncs.com/voice/tts/ws_xxx/audio_ee88b03d.mp3?Expires=1772697707&...",
      "id": "audio_ee88b03d",
      "expires_at": 1772697707
    }
  },
  "usage": {
    "characters": 31
  }
}

字段	类型	说明
`request_id`	string	全链路请求 ID
`output.finish_reason`	string	固定 `stop`（正常完成）
`output.audio.url`	string	带签名的临时下载地址，24h 有效
`output.audio.id`	string	音频资源 ID
`output.audio.expires_at`	int	URL 过期时间（Unix 秒）
`usage.characters`	int	计费字符数。开启 TN 时按归一化后文本计

3.4 错误响应

HTTP 状态码	error.code	说明
400	`InvalidParameter`	参数校验失败（含 voice 与 model 不匹配）
401	`Unauthorized`	凭证无效 / 缺失 / 过期
403	`Forbidden`	音色 / 模型越权；音色审核未通过
413	`TextTooLong`	文本超过 2000 字符
429	`RateLimitExceeded`	QPM 限流
500	`InternalError`	服务内部错误
503	`EngineUnavailable`	上游合成引擎不可用

3.5 完整请求示例

curl -X POST https://convai-platform.aliyuncs.com/v1/tts/synthesize \
  -H "Authorization: Bearer sk-9f2ac...d41b" \
  -H "Content-Type: application/json" \
  -H "X-TTS-TN: enable" \
  -d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "您的订单 12345 已完成。",
      "voice": "longxiaochun_v2",
      "format": "mp3",
      "sample_rate": 22050
    }
  }'

4. SSE 流式合成

4.1 请求

POST /v1/tts/synthesize
Authorization: Bearer <api_key>
Content-Type: application/json
X-TTS-SSE: enable

请求体与同步合成完全一致。通过请求头 X-TTS-SSE: enable 切换到 SSE 流式响应。

响应 Content-Type: text/event-stream，超时 5 分钟。

适用场景：短文本需要逐句获取音频，实现边合成边播放。

4.2 请求体

见第 2 节。

4.3 响应事件流示例

event: sentence-begin
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-begin","sentence":{"index":0},"original_text":"您的订单一二三四五已在二零二六年八月十二日完成。"}}

event: sentence-synthesis
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-synthesis","audio":{"data":"SUQz...（base64）"},"sentence":{"index":0}}}

event: sentence-end
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-end","sentence":{"index":0}},"usage":{"characters":24}}

event: sentence-begin
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-begin","sentence":{"index":1},"original_text":"预计三天内送达。"}}

event: sentence-synthesis
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-synthesis","audio":{"data":"SUQz...（base64）"},"sentence":{"index":1}}}

event: sentence-end
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-end","sentence":{"index":1}},"usage":{"characters":31}}

event: finish
data: {"request_id":"8ac1cd04-...","output":{"finish_reason":"stop","audio":{"url":"https://oss-.../full.mp3?Expires=...","id":"audio_xxx","expires_at":1772698611}},"usage":{"characters":31}}

4.4 事件序列

事件	时机	说明
`sentence-begin`	每句合成开始	包含句序号和文本
`sentence-synthesis`	每句音频块生成	包含 Base64 编码的音频数据
`sentence-end`	每句合成结束	包含累计计费字符数
`finish`	全部合成完成	包含完整音频 OSS 地址和总用量
`error`	任一环节失败	统一错误模型

4.5 事件载荷详解

sentence-begin — 句级开始

event: sentence-begin
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-begin","sentence":{"index":0},"original_text":"您的订单一二三四五已在二零二六年八月十二日完成。"}}

字段	类型	说明
`output.type`	string	固定 `sentence-begin`
`output.sentence.index`	int	句序号，从 0 递增
`output.original_text`	string	分句后的句子文本。开启 TN 时为归一化后文本

sentence-synthesis — 音频块

event: sentence-synthesis

data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-synthesis","audio":{"data":"<base64>"},"sentence":{"index":0,"words":[ ]}}}

字段	类型	说明
`output.type`	string	固定 `sentence-synthesis`
`output.audio.data`	string	Base64 编码的音频块，客户端解码后追加播放
`output.sentence.index`	int	所属句序号
`output.sentence.words`	array \| null	字级时间戳（仅 `word_timestamp_enabled=true` 时有值）

sentence-end — 句级结束

event: sentence-end
data: {"request_id":"8ac1cd04-...","output":{"type":"sentence-end","sentence":{"index":0}},"usage":{"characters":24}}

字段	类型	说明
`output.type`	string	固定 `sentence-end`
`output.sentence.index`	int	句序号
`usage.characters`	int	累计计费字符数

finish — 全部完成

event: finish
data: {"request_id":"8ac1cd04-...","output":{"finish_reason":"stop","audio":{"url":"https://oss-.../audio.mp3?Expires=...","id":"audio_xxx","expires_at":1772698611}},"usage":{"characters":55}}

字段	类型	说明
`output.finish_reason`	string	固定 `stop`
`output.audio.url`	string	完整音频的 OSS 签名 URL（所有句拼接后上传），24h 有效
`output.audio.id`	string	音频资源 ID
`output.audio.expires_at`	int	URL 过期时间
`usage.characters`	int	总累计计费字符数

error — 失败

event: error
data: {"request_id":"8ac1cd04-...","error":{"code":"EngineUnavailable","message":"Engine unavailable: upstream timeout","type":"server_error"}}

4.6 完整请求示例

curl -X POST https://convai-platform.aliyuncs.com/v1/tts/synthesize \
  -H "Authorization: Bearer sk-9f2ac...d41b" \
  -H "Content-Type: application/json" \
  --header 'X-TTS-SSE: enable' \
  -H "X-TTS-TN: enable" \
  -d '{
    "model": "cosyvoice-v3-flash",
    "input": {
      "text": "您的订单 12345 已完成。",
      "voice": "longxiaochun_v2",
      "format": "mp3",
      "sample_rate": 22050
    }
  }'