CosyVoice 的 HTTP 非实时语音合成接口，包含非流式和 SSE 流式调用、请求参数及返回字段。
接口地址
将 YOUR_WORKSPACE_ID 替换为对应地域的业务空间 ID，并使用同地域的 API Key。
- 华北2（北京）
POST https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer请求头
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | string | 必选 | 鉴权令牌，格式为 Bearer <your_api_key>。 |
Content-Type | string | 必选 | 固定为 application/json。 |
X-DashScope-SSE | string | 可选 | 流式输出时设置为 enable；未设置时返回完整结果。 |
调用示例
- 非流式
- 流式
SSE 事件可能包含多行
data:。合并同一事件的所有 data: 行后解析 JSON；将音频块按事件顺序 Base64 解码并拼接。结束帧的 output.finish_reason 为 stop，并返回完整音频 URL。请求体
| 参数 | 类型 | 必选 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 必选 | — | 语音合成模型 ID。支持的模型与地域请参见非实时语音合成。 |
input | object | 必选 | — | 输入参数对象。 |
input.text | string | 必选 | — | 待合成文本。使用 SSML 时同时设置 enable_ssml=true；LaTeX 输入无需额外配置。支持范围、标签和语法请参见 SSML 与 LaTeX。 |
input.voice | string | 必选 | — | 音色 ID。系统音色参见音色列表；自定义音色通过声音复刻或声音设计创建，并使用绑定的目标模型合成。 |
input.format | string | 可选 | mp3 | 音频编码格式。可选 mp3、pcm、wav、opus。 |
input.sample_rate | integer | 可选 | 22050 | 音频采样率（Hz）。可选 8000、12000、16000、22050、24000、44100、48000。format=opus 时仅支持 8000、12000、16000、24000、48000。 |
input.volume | integer | 可选 | 50 | 音量，取值范围 [0, 100]。 |
input.rate | float | 可选 | 1.0 | 语速，取值范围 [0.5, 2.0]。 |
input.bit_rate | integer | 可选 | 32 | 音频码率（kbps），取值范围 [6, 510]；仅在 format=opus 时生效。 |
input.pitch | float | 可选 | 1.0 | 音调，取值范围 [0.5, 2.0]。 |
input.enable_ssml | boolean | 可选 | — | 是否启用 SSML。模型、音色和接口限制请参见使用限制。 |
input.word_timestamp_enabled | boolean | 可选 | false | 是否返回字级别时间戳，仅用于流式输出。支持 cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 的复刻音色，以及音色列表中标记支持的系统音色。其他模型的复刻音色不支持。 |
input.seed | integer | 可选 | 0 | 随机种子，取值范围 [0, 65535]。模型版本、文本、音色和其他参数相同时，使用相同 seed 可复现相同合成结果。 |
input.language_hints | array[string] | 可选 | — | 合成目标语言，当前仅处理数组的第一个元素。此参数与复刻样本的源语言无关。数字、缩写、符号或小语种发音不符合预期时可设置，语言代码见下方列表。复刻源语言参见声音复刻 API。 |
input.instruction | string | 可选 | — | 控制方言、情感或角色等合成效果的指令。适用模型、音色与写法参见指令控制。 |
input.enable_aigc_tag | boolean | 可选 | false | 是否在 WAV、MP3、Opus 音频中嵌入 AIGC 隐性标识。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持。 |
input.aigc_propagator | string | 可选 | 阿里云 UID | 隐性标识的 ContentPropagator 字段，用于标识传播者；仅在 enable_aigc_tag=true 时生效。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持。 |
input.aigc_propagate_id | string | 可选 | 本次请求的 Request ID | 隐性标识的 PropagateID 字段，用于标识本次传播行为；仅在 enable_aigc_tag=true 时生效。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持。 |
input.hot_fix | object | 可选 | — | 文本热修复。pronunciation 自定义指定词语的发音，replace 在合成前替换指定文本。cosyvoice-v2 不支持。 |
input.enable_markdown_filter | boolean | 可选 | false | 是否在合成前过滤 Markdown 标记。仅 cosyvoice-v3-flash 的复刻音色支持。 |
语言编码
zh：中文en：英语fr：法语de：德语ja：日语ko：韩语ru：俄语pt：葡萄牙语th：泰语id：印尼语vi：越南语es：西班牙语it：意大利语ms：马来西亚语fil：菲律宾语ar：阿拉伯语
返回体
| 参数 | 类型 | 说明 |
|---|---|---|
request_id | string | 本次请求的唯一标识。 |
output | object | 模型输出对象。 |
output.finish_reason | string | 任务停止原因。null 表示合成中，stop 表示合成结束。 |
output.type | string | 仅流式输出返回。sentence-begin 表示句子开始；sentence-synthesis 表示音频块，同一句可包含多个块；sentence-end 表示句子结束并返回用量信息。音频块与数据帧一一对应，按顺序追加到同一文件。 |
output.original_text | string | 用户输入文本切分后的句子内容；最后一句可能没有此字段。 |
output.sentence | object | 句子信息。 |
output.sentence.index | integer | 句子编号，从 0 开始。 |
output.sentence.words | array | 句子中的字及其时间戳信息。 |
output.sentence.words[].text | string | 字。 |
output.sentence.words[].begin_index | integer | 字在句子中的开始位置，从 0 开始。 |
output.sentence.words[].end_index | integer | 字在句子中的结束位置，从 1 开始。 |
output.sentence.words[].begin_time | integer | 字对应音频的开始时间戳（毫秒）。 |
output.sentence.words[].end_time | integer | 字对应音频的结束时间戳（毫秒）。 |
output.audio | object | 合成音频对象。 |
output.audio.data | string | 流式输出的 Base64 音频块；非流式输出时为空。 |
output.audio.url | string | 完整音频文件的 URL，有效期 24 小时。 |
output.audio.id | string | 合成音频的标识。 |
output.audio.expires_at | integer | url 的过期时间戳。 |
usage | object | 用量信息。 |
usage.characters | integer | 累计计费字符数。 |
- 非流式
- 流式