本文介绍语音合成CosyVoice Python API的使用。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
快速开始
SpeechSynthesizer类提供了语音合成的关键接口,支持以下几种调用方式:
同步调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本合成场景。
异步调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的短文本语音合成场景。
流式调用:将文本逐步发送到服务端并实时接收语音合成结果,允许将长文本分段发送,服务端在接收到部分文本后便立即开始处理。适合实时性要求高的场景。
同步调用
提交单个语音合成任务,无需调用回调函数,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。
实例化SpeechSynthesizer类绑定请求参数,调用call
方法进行合成并获取二进制音频数据。
异步调用
提交单个语音合成任务,通过回调的方式流式输出中间结果,合成结果通过ResultCallback
中的回调函数流式获取。
实例化SpeechSynthesizer类绑定请求参数和回调接口(ResultCallback),调用call
方法进行合成并通过回调接口(ResultCallback)的on_data
方法实时获取合成结果。
流式调用
在同一个语音合成任务中分多次提交文本,并通过回调的方式实时获取合成结果。
流式输入时可多次调用
streaming_call
按顺序提交文本片段。服务端接收文本片段后自动进行分句:完整语句立即合成
不完整语句缓存至完整后合成
调用
streaming_complete
时,服务端会强制合成所有已接收但未处理的文本片段(包括未完成的句子)。发送文本片段的间隔不得超过23秒,否则触发“request timeout after 23 seconds”异常。
若无待发送文本,需及时调用
streaming_complete
结束任务。服务端强制设定23秒超时机制,客户端无法修改该配置。
实例化SpeechSynthesizer类
流式传输
循环调用SpeechSynthesizer类的
streaming_call
方法分片提交待合成文本,将待合成文本分段发送至服务端。在发送文本的过程中,服务端会通过回调接口(ResultCallback)的
on_data
方法,将合成结果实时返回给客户端。结束处理
调用SpeechSynthesizer类的
streaming_complete
方法结束语音合成。该方法会阻塞当前线程,直到回调接口(ResultCallback)的
on_complete
或者on_error
回调触发后才会释放线程阻塞。
请求参数
请求参数通过SpeechSynthesizer类的构造方法进行设置。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | str | - | 是 | 指定模型,支持 |
voice | str | - | 是 | 指定语音合成所使用的音色。 支持如下两种音色:
|
format | enum | 因音色而异 | 否 | 指定音频编码格式及采样率。 若未指定 可指定的音频编码格式及采样率如下:
|
volume | int | 50 | 否 | 合成音频的音量,取值范围:0~100。 该字段在不同版本的DashScope SDK中有所不同:
|
speech_rate | float | 1.0 | 否 | 合成音频的语速,取值范围:0.5~2。
|
pitch_rate | float | 1.0 | 否 | 合成音频的语调,取值范围:0.5~2。 |
callback | ResultCallback | - | 否 |
关键接口
SpeechSynthesizer
类
SpeechSynthesizer
通过“from dashscope.audio.tts_v2 import *
”方式引入,提供语音合成的关键接口。
方法 | 参数 | 返回值 | 描述 |
方法 | 参数 | 返回值 | 描述 |
|
| 没有指定 | 将整段文本转换为语音。
|
|
| 无 | 流式发送待合成文本。 您可以多次调用该接口,将待合成文本分多次发送给服务端。合成结果通过回调接口(ResultCallback)的 必须在所有 使用方法请参见流式调用。 |
|
| 无 | 结束流式语音合成。 该方法阻塞当前线程N毫秒(具体时长由 默认情况下,如果等待时间超过10分钟,则停止等待。 使用方法请参见流式调用。 |
| 无 | 上一个任务的request_id | 获取上一个任务的request_id。 |
| 无 | 首包延迟 | 获取首包延迟。 首包延迟是开始发送文本和接收第一个音频包之间的时间,单位为毫秒。在任务完成后使用。 |
| 无 | 最后一次报文 | 获取最后一次报文(为JSON格式的数据),可以用于获取task-failed报错。 |
回调接口(ResultCallback
)
异步调用或流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
方法 | 参数 | 返回值 | 描述 |
方法 | 参数 | 返回值 | 描述 |
| 无 | 无 | 当和服务端建立连接完成后,该方法立刻被回调。 |
|
| 无 | 当服务有回复时会被回调。 |
| 无 | 无 | 当所有合成数据全部返回后被回调。 |
|
| 无 | 发生异常时该方法被回调。 |
|
| 无 | 当服务器有合成音频返回时被回调。 |
| 无 | 无 | 当服务已经关闭连接后被回调。 |
响应结果
服务器返回二进制音频数据:
同步调用:对SpeechSynthesizer类的
call
方法返回的二进制音频数据进行处理。异步调用或流式调用:对回调接口(ResultCallback)的
on_data
方法的参数(bytes类型数据)进行处理。
错误码
在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。
更多示例
更多示例,请参见GitHub。
常见问题
请参见GitHub QA。
音色列表
当前默认支持的音色如下表所示。若您需要更加个性化的音色,可通过声音复刻功能免费定制专属音色,详情请参见使用复刻的音色进行语音合成。
默认采样率代表当前音色的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如龙小淳音色,默认采样率22.05 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。
音色 | 音频试听(右键保存音频) | model参数 | voice参数 | 适用场景 | 语言 | 默认采样率(Hz) | 默认音频格式 |
音色 | 音频试听(右键保存音频) | model参数 | voice参数 | 适用场景 | 语言 | 默认采样率(Hz) | 默认音频格式 |
龙婉 | cosyvoice-v1 | longwan | 语音助手、 导航播报、 聊天数字人 | 中文普通话 | 22050 | mp3 | |
龙橙 | cosyvoice-v1 | longcheng | 语音助手、 导航播报、 聊天数字人 | 中文普通话 | 22050 | mp3 | |
龙华 | cosyvoice-v1 | longhua | 语音助手、 导航播报、 聊天数字人 | 中文普通话 | 22050 | mp3 | |
龙小淳 | cosyvoice-v1 | longxiaochun | 语音助手、 导航播报、 聊天数字人 | 中文+英文 | 22050 | mp3 | |
龙小夏 | cosyvoice-v1 | longxiaoxia | 语音助手、聊天数字人 | 中文 | 22050 | mp3 | |
龙小诚 | cosyvoice-v1 | longxiaocheng | 语音助手、导航播报、聊天数字人 | 中文+英文 | 22050 | mp3 | |
龙小白 | cosyvoice-v1 | longxiaobai | 聊天数字人、有声书、语音助手 | 中文 | 22050 | mp3 | |
龙老铁 | cosyvoice-v1 | longlaotie | 新闻播报、有声书、语音助手、直播带货、导航播报 | 中文东北口音 | 22050 | mp3 | |
龙书 | cosyvoice-v1 | longshu | 有声书、语音助手、导航播报、新闻播报、智能客服 | 中文 | 22050 | mp3 | |
龙硕 | cosyvoice-v1 | longshuo | 语音助手、导航播报、新闻播报、客服催收 | 中文 | 22050 | mp3 | |
龙婧 | cosyvoice-v1 | longjing | 语音助手、导航播报、新闻播报、客服催收 | 中文 | 22050 | mp3 | |
龙妙 | cosyvoice-v1 | longmiao | 客服催收、导航播报、有声书、语音助手 | 中文 | 22050 | mp3 | |
龙悦 | cosyvoice-v1 | longyue | 语音助手、诗词朗诵、有声书朗读、导航播报、新闻播报、客服催收 | 中文 | 22050 | mp3 | |
龙媛 | cosyvoice-v1 | longyuan | 有声书、语音助手、聊天数字人 | 中文 | 22050 | mp3 | |
龙飞 | cosyvoice-v1 | longfei | 会议播报、新闻播报、有声书 | 中文 | 22050 | mp3 | |
龙杰力豆 | cosyvoice-v1 | longjielidou | 新闻播报、有声书、聊天助手 | 中文+英文 | 22050 | mp3 | |
龙彤 | cosyvoice-v1 | longtong | 有声书、导航播报、聊天数字人 | 中文 | 22050 | mp3 | |
龙祥 | cosyvoice-v1 | longxiang | 新闻播报、有声书、导航播报 | 中文 | 22050 | mp3 | |
Stella | cosyvoice-v1 | loongstella | 语音助手、直播带货、导航播报、客服催收、有声书 | 中文+英文 | 22050 | mp3 | |
Bella | cosyvoice-v1 | loongbella | 语音助手、客服催收、新闻播报、导航播报 | 中文 | 22050 | mp3 |
升级CosyVoice2.0说明
部分音色支持升级使用CosyVoice2.0模型,升级方法:
model
字段替换为"cosyvoice-v2"voice
字段使用CosyVoice2.0音色
升级后调用方法和计费不变,默认QPS为3。支持升级的音色包括:
升级前voice参数 | 升级后voice参数 |
longcheng | longcheng_v2 |
longhua | longhua_v2 |
longshu | longshu_v2 |
loongbella | loongbella_v2 |
longwan | longwan_v2 |
longxiaochun | longxiaochun_v2 |
longxiaoxia | longxiaoxia_v2 |
更多的音色会陆续上线,敬请期待。
目前cosyvoice-v2服务只支持使用主账号调用。
- 本页导读 (1)
- 前提条件
- 快速开始
- 同步调用
- 异步调用
- 流式调用
- 请求参数
- 关键接口
- SpeechSynthesizer类
- 回调接口(ResultCallback)
- 响应结果
- 错误码
- 更多示例
- 常见问题
- 音色列表
- 升级CosyVoice2.0说明