本文介绍语音合成CosyVoice Java API的使用。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
语音合成文本限制与格式规范
文本长度限制
字符计算规则
汉字:2字符
英文字母/数字/标点/空格:1字符
示例:
"你好"
→ 2+2=4字符"中A文123"
→ 2+1+2+1+1+1=8字符"中文。"
→ 2+2+1=5字符"中 文。"
→ 2+1+2+1=6字符
编码格式
需采用UTF-8编码。
数学表达式支持
适用范围:仅
cosyvoice-v2
模型支持范围:中小学常见数学表达式(如基础运算、代数、几何等),详情请参见Latex能力支持说明
快速开始
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;
”方式引入,提供语音合成的关键接口。
接口/方法 | 参数 | 返回值 | 描述 |
|
|
| 构造函数。
|
|
|
| 将整段文本转换为语音。 在创建
|
|
| 无 | 流式发送待合成文本。 您可以多次调用该接口,将待合成文本分多次发送给服务端。合成结果通过回调接口(ResultCallback)的 详细调用流程和参考示例请参见流式调用。 |
| 无 | 无 | 结束流式语音合成。 该方法阻塞调用线程直至发生以下条件之一:
详细的调用流程和参考示例请参见流式调用。 重要 流式调用时,请确保调用该方法,以免导致合成语音缺失。 |
|
| 合成结果,封装在 | 非流式文本输入实时转换为流式语音输出,合成结果在flowable中流式返回。 详细的调用流程和参考示例请参见通过Flowable调用。 |
|
| 合成结果,封装在 | 流式文本输入实时转换为流式语音输出,合成结果在flowable中流式返回。 详细的调用流程和参考示例请参见通过Flowable调用。 |
| 无 | 上一个任务的Request ID | 获取上一个任务的Request ID,在调用 |
| 无 | 当前任务首包延迟 | 获取当前任务的首包延迟,任务结束后使用。 首包延迟是开始发送文本和接收第一个音频包之间的时间,单位为毫秒。 |
回调接口(ResultCallback
)
在异步调用或流式调用时,通过回调接口ResultCallback
获取合成结果。通过“import com.alibaba.dashscope.common.ResultCallback;
”方式引入。
接口/方法 | 参数 | 返回值 | 描述 |
|
| 无 | 当服务端推送语音合成数据时被异步回调。 调用SpeechSynthesisResult的 |
| 无 | 无 | 当所有合成数据全部返回(语音合成完成)后被异步回调。 |
|
| 无 | 发生异常时该接口被异步回调。 建议在 |
响应结果
服务器返回二进制音频数据:
同步调用:对SpeechSynthesizer类的
call
方法返回的二进制音频数据进行处理。异步调用或流式调用:对回调接口(ResultCallback)的
onEvent
方法的参数(SpeechSynthesisResult
类型)进行处理。SpeechSynthesisResult
的关键接口如下:接口/方法
参数
返回值
描述
public ByteBuffer getAudioFrame()
无
二进制音频数据
返回当前流式合成片段的二进制音频数据,可能为空(当无新数据到达时)。
您可以将二进制音频数据合成为一个完整的音频文件后使用播放器播放,也可以通过支持流式播放的播放器实时播放。
重要流式语音合成中,音频分段传输,需使用流式播放器,不可逐帧播放,避免解码失败。
支持流式播放的播放器:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
将音频数据合成完整的音频文件时,应以追加模式写入同一文件。
流式语音合成的wav/mp3 格式音频仅首帧包含头信息,后续帧为纯音频数据。
public String getRequestId()
无
任务的Request ID
获取任务的Request ID。当调用
getAudioFrame
获取到二进制音频数据时,getRequestId
方法的返回值为null
。
错误码
语音合成中常见错误码如下,如遇其他报错问题,请参见错误信息进行排查。
错误码(Code) | 错误信息(Message) | 说明 |
InvalidParameter | request timeout after 23 seconds | 流式调用(流式调用或Flowable流式调用)时,超过23秒未向服务端发送文本且服务端无任何音频返回。 请检查为什么长时间未发送文本,例如,长时间未收到大语言模型返回的文本,因此未能及时向CosyVoice模型发送文本。 如果长时间(超过23秒)不向服务端发送消息,请及时调用SpeechSynthesizer类的 |
[tts:]Engine return error code: 418 | 请按以下步骤检查请求参数 | |
network error | InputRequiredException: Parameter invalid: text is null | 此错误通常是由于未发送待合成文本引起的。 请根据以下可能原因进行排查:
|
Throttling.RateQuota | Requests rate limit exceeded, please try again later. | 调用接口频率过高,已超出语音合成大模型的并发限制,详情请参见限流。 |
InvalidApiKey | Invalid API-key provided. | API Key无效。 检查并确认API Key(在获取API Key的操作指引中可查看)是否正确,确保无多出空格或缺少字母等问题。 |
Model.AccessDenied | Model access denied. | 出现该问题的原因是使用了子业务空间的API Key调用模型,请根据调用的模型版本进行排查:
|
更多示例
更多示例,请参见GitHub。
升级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服务只支持使用默认业务空间的API Key调用。
音色列表
当前默认支持的音色如下表所示。若您需要更加个性化的音色,可通过声音复刻功能免费定制专属音色,详情请参见使用复刻的音色进行语音合成。
默认采样率代表当前音色的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。
如龙小淳音色,默认采样率22.05 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。
如果当前音色在“语言”列中未明确标注支持的口音,则表明该音色不区分具体口音。
音色 | 音频试听(右键保存音频) | 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 |
常见问题
功能特性/计量计费/限流
Q:我想了解CosyVoice的功能特性、计量计费、限流等信息,应该去哪里查看?
以上信息可在语音合成-CosyVoice中查看。
Q:由于CosyVoice不支持SSML,当遇到发音不准的情况时,是否有其他临时解决方案可以尝试?
可以尝试使用同音字替换发音不准的文字,以改善语音合成效果。
Q:当前RPS(Requests Per Second)无法满足实际业务需求,该怎么办?如何扩容?是否收费?
Q:cosyvoice-v1 和 cosyvoice-v2 有什么区别?计费方式是否不同?
v1 和 v2 在编码方式上相同,但使用时需注意请求参数 model
和 voice
的设置需匹配实际版本(如 v2 模型需使用 v2 音色,否则会报错)。
v1 和 v2 的计费方式完全一致。
故障排查
如遇代码报错问题,请根据错误码中的信息进行排查。
Q:如何获取Request ID?
通过以下两种方式可以获取:
在回调接口(ResultCallback)的
onEvent
方法中调用SpeechSynthesisResult的getRequestId
方法。getRequestId
方法返回值可能为null,详情请参见SpeechSynthesisResult中关于getRequestId
方法的描述。调用SpeechSynthesizer的
getLastRequestId
方法。
Q:为什么音频无法播放?
请根据以下场景逐一排查:
音频保存为完整文件(如xx.mp3)的情况
音频格式一致性:确保请求参数中设置的音频格式与文件后缀一致。例如,如果请求参数设置的音频格式为wav,但文件后缀为mp3,可能会导致播放失败。
播放器兼容性:确认使用的播放器是否支持该音频文件的格式和采样率。例如,某些播放器可能不支持高采样率或特定编码的音频文件。
流式播放音频的情况
将音频流保存为完整文件,尝试使用播放器播放。如果文件无法播放,请参考场景 1 的排查方法。
如果文件可以正常播放,则问题可能出在流式播放的实现上。请确认使用的播放器是否支持流式播放。
常见的支持流式播放的工具和库包括:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
Q:为什么音频播放卡顿?
请根据以下场景逐一排查:
音频保存为完整文件(如xx.mp3)的情况
流式播放音频的情况
检查文本发送速度: 确保发送文本的间隔合理,避免前一句音频播放完毕后,下一句文本未能及时发送。
检查回调函数性能:
检查回调函数中是否存在过多业务逻辑,导致阻塞。
回调函数运行在 WebSocket 线程中,若被阻塞,可能会影响 WebSocket 接收网络数据包,进而导致音频接收卡顿。
建议将音频数据写入一个独立的音频缓冲区(audio buffer),然后在其他线程中读取并处理,避免阻塞 WebSocket 线程。
检查网络稳定性: 确保网络连接稳定,避免因网络波动导致音频传输中断或延迟。
进一步排查: 如果以上方法仍未解决问题,请提交阿里云工单或加入开发者群,并提供Request ID,以便我们为您进一步排查问题。
Q:为什么没有返回语音?为什么结尾部分的文本没能成功转换成语音?(合成语音缺失)
请检查是否遗漏了调用SpeechSynthesizer类的streamingComplete
方法。在语音合成过程中,服务端会在缓存足够文本后才开始合成。如果未调用streamingComplete
方法,可能会导致缓存中的结尾部分文本未能被合成为语音。
Q:运行代码报NoApiKeyException,提示“Can not find api-key”是什么原因?
出现该问题的原因是没有配置API Key到环境变量,且在请求参数中没有设置apiKey
。您需要配置API Key到环境变量或在请求参数中设置apiKey
。
权限与认证
Q:我希望我的 API Key 仅用于 CosyVoice 语音合成服务,而不被百炼其他模型使用(权限隔离),我该如何做?
可以通过新建业务空间并只授权特定模型来限制API Key的使用范围。详情请参见如何使用业务空间。
Q:为什么运行代码后提示我Model.AccessDenied
/Workspace.AccessDenied
?该如何解决?
模型访问被拒绝。
出现该问题的原因是使用了子业务空间的API Key调用模型,请根据调用的模型版本进行排查:
cosyvoice-v1
:请使用默认业务空间的API Key(参见获取API Key)进行调用。如果想使用子业务空间API Key,请参见子业务空间的模型调用,为API Key对应的子业务空间进行模型授权。cosyvoice-v2
:目前cosyvoice-v2
模型仅支持使用默认业务空间的API Key进行调用,请使用默认业务空间的API Key(参见获取API Key)。
Q:使用子业务空间的API Key是否可以调用CosyVoice模型?
对于默认业务空间,cosyvoice-v1
和cosyvoice-v2
均可调用。
对于子业务空间:
cosyvoice-v1
:支持,但是需要为API Key对应的子业务空间进行模型授权,详情请参见子业务空间的模型调用。cosyvoice-v1
:不支持。
更多问题
请参见GitHub QA。