本文介绍语音合成CosyVoice Java API的使用。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
快速开始
SpeechSynthesizer类提供了语音合成的关键接口,支持以下几种调用方式:
同步调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本语音合成场景。
异步调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的短文本语音合成场景。
流式调用:将文本逐步发送到服务端并实时接收语音合成结果,允许将长文本分段发送,服务端在接收到部分文本后便立即开始处理。适合实时性要求高的长文本语音合成场景。
同步调用
同步提交语音合成任务,直接获取完整结果。
实例化SpeechSynthesizer类绑定请求参数,调用call
方法进行合成并获取二进制音频数据。
发送的文本长度不得超过2000字符(详情请参见SpeechSynthesizer类的call
方法)。
异步调用
异步提交语音合成任务,通过注册ResultCallback
回调,逐帧接收实时语音分段数据。
实例化SpeechSynthesizer类绑定请求参数和回调接口(ResultCallback),调用call
方法进行合成并通过回调接口(ResultCallback)的onEvent
方法实时获取合成结果。
发送的文本长度不得超过2000字符(详情请参见SpeechSynthesizer类的call
方法)。
流式调用
分多次提交文本,通过注册ResultCallback
回调,逐帧接收实时语音分段数据。
流式输入时可多次调用
streamingCall
按顺序提交文本片段。服务端接收文本片段后自动进行分句:完整语句立即合成
不完整语句缓存至完整后合成
调用
streamingComplete
时,服务端会强制合成所有已接收但未处理的文本片段(包括未完成的句子)。发送文本片段的间隔不得超过23秒,否则触发“request timeout after 23 seconds”异常。
若无待发送文本,需及时调用
streamingComplete
结束任务。服务端强制设定23秒超时机制,客户端无法修改该配置。
实例化SpeechSynthesizer类
流式传输
多次调用SpeechSynthesizer类的
streamingCall
方法分片提交待合成文本,将待合成文本分段发送至服务端。在发送文本的过程中,服务端会通过回调接口(ResultCallback)的
onEvent
方法,将合成结果实时返回给客户端。每次调用
streamingCall
方法发送的文本片段(即text
)长度不得超过2000字符,累计发送的文本总长度不得超过20万字符。结束处理
调用SpeechSynthesizer类的
streamingComplete
方法结束语音合成。该方法会阻塞当前线程,直到回调接口(ResultCallback)的
onComplete
或者onError
回调触发后才会释放线程阻塞。
通过Flowable调用
Flowable是一个用于工作流和业务流程管理的开源框架,它基于Apache 2.0许可证发布。关于Flowable的使用,请参见Flowable API详情。
使用Flowable前需确保已集成RxJava库,并了解响应式编程基础概念。
以下示例展示了通过Flowable对象的blockingForEach
接口,阻塞式地获取每次流式返回的SpeechSynthesisResult
类型数据。
您也可以在Flowable的所有流式数据返回完成后,通过SpeechSynthesizer类的getAudioData
来获取完整的合成结果。
以下示例展示了通过Flowable对象作为输入参数,输入文本流。并通过Flowable对象作为返回值,利用的blockingForEach
接口,阻塞式地获取每次流式返回的SpeechSynthesisResult
类型数据。
您也可以在Flowable的所有流式数据返回完成后,通过SpeechSynthesizer类的getAudioData
来获取完整的合成结果。
高并发调用
在DashScope Java SDK中,采用了OkHttp3的连接池技术,以减少重复建立连接的开销。详情请参见高并发场景。
请求参数
通过SpeechSynthesisParam
的链式方法配置模型、音色等参数。配置完成的参数对象传入SpeechSynthesizer类的构造函数中使用。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | String | - | 是 | 指定模型,支持 |
voice | String | - | 是 | 指定语音合成所使用的音色。 支持如下两种音色:
|
format | enum | 因音色而异 | 否 | 指定音频编码格式及采样率。 若未指定 可指定的音频编码格式及采样率如下:
|
volume | int | 50 | 否 | 指定音量,取值范围:0~100。 |
speechRate | float | 1.0 | 否 | 指定语速,取值范围:0.5~2。
|
pitchRate | float | 1.0 | 否 | 指定语调,取值范围:0.5~2。 |
apiKey | String | - | 否 | 指定用户API Key。 |
关键接口
SpeechSynthesizer
类
SpeechSynthesizer
通过“import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
”方式引入,提供语音合成的关键接口。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
|
|
| 构造函数。 当您使用异步调用或流式调用模式时,请将callback参数设置为回调接口(ResultCallback)。 当您使用同步调用或通过Flowable调用模式时,请将callback参数设为null。 |
|
|
| 将整段文本转换为语音。 在创建
注意: 调用 字符计算规则: 1个汉字算作2个字符。 1个英文字母、1个标点或1个句子中间的空格均算作1个字符。 |
|
| 无 | 流式发送待合成文本。 您可以多次调用该接口,将待合成文本分多次发送给服务端。合成结果通过回调接口(ResultCallback)的 详细调用流程和参考示例请参见流式调用。 注意:
|
| 无 | 无 | 结束流式语音合成。 该方法阻塞调用线程直至发生以下条件之一:
详细的调用流程和参考示例请参见流式调用。 |
|
| 合成结果,封装在 | 非流式文本输入实时转换为流式语音输出,合成结果在flowable中流式返回。 详细的调用流程和参考示例请参见通过Flowable调用。 |
|
| 合成结果,封装在 | 流式文本输入实时转换为流式语音输出,合成结果在flowable中流式返回。 详细的调用流程和参考示例请参见通过Flowable调用。 |
| 无 | 当前上一个任务的request id | 获取上一个任务的request id,在调用 |
| 无 | 当前任务首包延迟 | 获取当前任务的首包延迟,任务结束后使用。 首包延迟是开始发送文本和接收第一个音频包之间的时间,单位为毫秒。 |
回调接口(ResultCallback
)
在异步调用或流式调用时,通过回调接口ResultCallback
获取合成结果。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
|
| 无 | 当服务端推送语音合成数据时被异步回调。 调用SpeechSynthesisResult的 |
| 无 | 无 | 当语音合成完成后被异步回调。 |
|
| 无 | 发生异常时该接口被异步回调。 建议在 |
响应结果
服务器返回二进制音频数据:
同步调用:对SpeechSynthesizer类的
call
方法返回的二进制音频数据进行处理。异步调用或流式调用:对回调接口(ResultCallback)的
onEvent
方法的参数(SpeechSynthesisResult
类型)进行处理。SpeechSynthesisResult
的关键接口如下:接口/方法
参数
返回值
描述
接口/方法
参数
返回值
描述
public ByteBuffer getAudioFrame()
无
二进制音频数据
返回当前流式合成片段的二进制音频数据,可能为空(当无新数据到达时)。
您可以将二进制音频数据合成为一个完整的音频文件后使用播放器播放,也可以通过支持流式播放的播放器实时播放。
在流式语音合成中,完整的音频文件会被分多次返回。播放流式音频时,需要使用支持流式播放的音频播放器,而不是将每一帧作为独立的音频进行播放,否则可能导致解码失败。
支持流式播放的播放器:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
将音频数据合成为一个完整的音频文件时,请以追加模式将数据写入同一个文件。
在使用wav或mp3格式进行流式语音合成时,文件头信息仅包含在第一帧中,后续帧为纯音频数据。
错误码
在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。
更多示例
更多示例,请参见GitHub。
常见问题
请参见GitHub QA。
升级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服务只支持使用主账号调用。
音色列表
当前默认支持的音色如下表所示。若您需要更加个性化的音色,可通过声音复刻功能免费定制专属音色,详情请参见使用复刻的音色进行语音合成。
默认采样率代表当前音色的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。
如龙小淳音色,默认采样率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 |
- 本页导读 (1)
- 前提条件
- 快速开始
- 同步调用
- 异步调用
- 流式调用
- 通过Flowable调用
- 高并发调用
- 请求参数
- 关键接口
- SpeechSynthesizer类
- 回调接口(ResultCallback)
- 响应结果
- 错误码
- 更多示例
- 常见问题
- 升级CosyVoice2.0说明
- 音色列表