CosyVoice HTTP API - 大模型服务平台百炼

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`；未设置时返回完整结果。

调用示例

非流式

curl -X POST "https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "我家的后面有一个很大的花园。",
    "voice": "longanyang",
    "format": "wav",
    "sample_rate": 24000
  }
}'

流式

curl --no-buffer -X POST "https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-SSE: enable" \
  -d '{
  "model": "cosyvoice-v3-flash",
  "input": {
    "text": "我家的后面有一个很大的花园。",
    "voice": "longanyang",
    "format": "wav",
    "sample_rate": 24000
  }
}'

说明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：阿拉伯语

文本热修复配置示例：

{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}

返回体

参数	类型	说明
`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`	累计计费字符数。

非流式

{
  "output": {
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570,
      "url": "https://example.com/output.wav"
    },
    "finish_reason": "stop"
  },
  "usage": {
    "characters": 27
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

流式

中间结果：

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "output": {
    "finish_reason": null,
    "type": "sentence-begin",
    "original_text": "我家的后面有一个很大的花园。",
    "sentence": {
      "index": 0,
      "words": []
    },
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570
    }
  }
}

最终结果：

{
  "output": {
    "audio": {
      "data": "",
      "id": "audio_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "expires_at": 1792079570,
      "url": "https://example.com/output.wav"
    },
    "finish_reason": "stop"
  },
  "usage": {
    "characters": 27
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}