跳转到主要内容
千问云 home page
开放平台文档
CosyVoice

CosyVoice 语音合成 API 参考

CosyVoice 语音合成 DashScope HTTP API，支持非流式和 SSE 流式两种模式，将文本转换为音频。

请求端点

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

请求头

参数类型是否必选说明
Authorizationstring必选鉴权令牌，格式为 Bearer $DASHSCOPE_API_KEY
Content-Typestring必选请求体的媒体类型，固定为 application/json
X-DashScope-SSEstring可选设置为 enable 时开启 SSE 流式输出

请求体

顶层字段

参数类型是否必选说明
modelstring必选语音合成模型。可选值：cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash、cosyvoice-v2
inputobject必选输入参数对象，详见 input 参数

input 参数

参数类型是否必选说明
textstring必选待合成文本。支持 SSML 和 LaTeX 公式 格式输入。使用 SSML 时需同时将 enable_ssml 设置为 true；使用 LaTeX 时无需额外配置
voicestring必选音色。可选值：系统音色（参见音色列表）、声音复刻音色、声音设计音色（创建方法参见 CosyVoice 声音复刻/设计 API）
formatstring可选音频编码格式。默认值：mp3。可选值：mp3、pcm、wav、opus
sample_rateinteger可选音频采样率（单位：Hz）。默认值：22050。可选值：8000、16000、22050、24000、44100、48000。默认采样率代表当前音色的最佳采样率，同时支持降采样或升采样
volumeinteger可选音量。默认值：50。取值范围：[0, 100]。50 代表标准音量，0 为静音，100 为最大音量，音量大小与该值呈线性关系
ratefloat可选语速。默认值：1.0。取值范围：[0.5, 2.0]。1.0 为标准语速，小于 1.0 则减慢，大于 1.0 则加快
bit_rateinteger可选音频码率（单位：kbps）。默认值：32。取值范围：[6, 510]。仅在 format 为 opus 时支持
pitchfloat可选音高。该值作为音高调节的乘数，与听感上的音高变化并非严格线性关系，建议通过测试选择合适的值。默认值：1.0。取值范围：[0.5, 2.0]。1.0 为音色自然音高，大于 1.0 音高升高，小于 1.0 音高降低
enable_ssmlboolean可选是否开启 SSML 功能
word_timestamp_enabledboolean可选是否开启字级别时间戳。默认值：false。仅适用于 cosyvoice-v3-flash、cosyvoice-v3-plus 和 cosyvoice-v2 的复刻音色，以及音色列表中标记为支持的系统音色
seedinteger可选生成时使用的随机数种子，用于复现相同合成结果。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的 seed 可复现相同的合成结果。默认值：0。取值范围：[0, 65535]
language_hintsarray[string]可选指定语音合成的目标语言，提升合成效果。当数字、缩写、符号等朗读方式或小语种合成效果不符合预期时使用。可选值：zh、en、fr、de、ja、ko、ru、pt、th、id、vi。注意：此参数为数组，当前版本仅处理第一个元素，建议只传入一个值
instructionstring可选设置指令，用于控制方言、情感或角色等合成效果。长度限制：100 字符（汉字按 2 个字符计算）。仅适用于 cosyvoice-v3.5-flash、cosyvoice-v3.5-plus 和 cosyvoice-v3-flash 的复刻音色，以及音色列表中标记为支持 Instruct 的系统音色
enable_aigc_tagboolean可选是否在生成的音频中添加 AIGC 隐性标识。设置为 true 时，将隐性标识嵌入到支持格式（wav/mp3/opus）的音频中。默认值：false。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持
aigc_propagatorstring可选设置 AIGC 隐性标识中的 ContentPropagator 字段，用于标识内容传播者。仅在 enable_aigc_tag 为 true 时生效。默认值：阿里云 UID。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持
aigc_propagate_idstring可选设置 AIGC 隐性标识中的 PropagateID 字段，用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。默认值：本次请求的 Request ID。仅 cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 支持
hot_fixobject可选文本热修复配置，用于自定义指定词语的发音或对待合成文本进行替换。仅 cosyvoice-v3-flash 复刻音色支持。详见 hot_fix 参数
enable_markdown_filterboolean可选是否启用 Markdown 过滤。启用后，系统在合成语音前自动过滤输入文本中的 Markdown 标记符号，避免将其朗读为文字内容。默认值：false。仅 cosyvoice-v3-flash 复刻音色支持

hot_fix 参数

参数类型说明
pronunciationarray[object]自定义发音。指定词语的拼音标注，用于纠正默认发音不准确的情况。拼音采用数字标调格式，如 tian1 qi4 表示 tiān qì。示例：[{"天气": "tian1 qi4"}]
replacearray[object]文本替换。在语音合成前将指定词语替换为目标文本，替换后的文本将作为实际合成内容。示例：[{"今天": "金天"}]
hot_fix 示例： 
{
  "hot_fix": {
    "pronunciation": [
      {"天气": "tian1 qi4"}
    ],
    "replace": [
      {"今天": "金天"}
    ]
  }
}

请求示例

curl -X POST https://dashscope.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
  }
}'

响应体

顶层字段

参数类型说明
request_idstring本次调用的唯一标识符
outputobject模型返回的数据，详见 output 字段
usageobject用量信息，详见 usage 字段

output 字段

参数类型说明
finish_reasonstring任务停止原因。"null"=语音合成中；"stop"=语音合成结束
typestring子事件类型，仅流式合成时返回。sentence-begin=句子开始，返回待合成的句子文本；sentence-synthesis=音频数据块，一个句子合成过程中会产生多个此事件，需按顺序追加写入同一文件；sentence-end=句子结束，返回句子文本内容和累计计费字符数
original_textstring对用户输入文本进行分句后的句内容。最后一个句子通常不包含此字段，建议在解析时做空值处理
sentenceobject句子信息，详见 sentence 字段
audioobject合成的音频数据，详见 audio 字段

sentence 字段

参数类型说明
indexinteger句子的编号，从 0 开始
wordsarray每句话对应的字的信息，详见 words 字段

words 字段

参数类型说明
textstring字
begin_indexinteger字在句子中的开始位置索引，从 0 开始
end_indexinteger字在句子中的结束位置索引，从 1 开始
begin_timeinteger字对应音频的开始时间戳（毫秒）
end_timeinteger字对应音频的结束时间戳（毫秒）

audio 字段

参数类型说明
datastring流式合成时输出 Base64 格式音频数据；非流式合成时为空
urlstring模型输出的完整音频文件的 URL，有效期 24 小时
idstring模型输出的音频信息对应的 ID
expires_atintegerurl 过期的 Unix 时间戳（秒）

usage 字段

参数类型说明
charactersinteger输入文本的计费字符数（中文字符按 2 个计费单位计算，ASCII 字符按 1 个计费单位计算）

响应示例

{
  "request_id": "ee88b03d-0457-9286-8c67-xxxxxxxxxxxx",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/cosyvoice-v3-flash/20260304/xxxxxxxx/ee88b03d-0457-9286-8c67-xxxxxxxxxxxx.wav?xxxxxxx",
      "id": "audio_ee88b03d-0457-9286-8c67-xxxxxxxxxxxx",
      "expires_at": 1772697707
    }
  },
  "usage": {
    "characters": 25
  }
}