CosyVoice Java 参考文档
模型概览和音色选择请参见语音合成。
SDK 默认服务端点为
请参见语音合成。
使用 UTF-8 编码。
cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持数学表达式解析,覆盖常见的中小学数学内容,包括基本运算、代数和几何。
请参见将 LaTeX 公式转为语音(仅限中文)。
SSML 适用于 cosyvoice-v3-flash 和 cosyvoice-v3-plus 上的自定义音色(声音设计或声音克隆),以及音色列表中标注支持 SSML 的系统音色。
使用要求:
SpeechSynthesizer 类支持以下调用方式:
同步发送文本,返回完整音频结果。
实例化 SpeechSynthesizer,绑定请求参数,然后调用
异步提交文本,通过
实例化 SpeechSynthesizer,绑定请求参数和 ResultCallback,然后调用
分多次发送文本片段,通过
Flowable 是 Apache 2.0 协议下的开源响应式编程框架,详情请参见 Flowable API 文档。使用前请先集成 RxJava 库并了解响应式编程基础。
DashScope Java SDK 使用 OkHttp3 连接池来减少连接开销。请参见高并发管理。
通过 SpeechSynthesisParam 的链式方法配置 model、voice 等参数,将配置好的对象传给 SpeechSynthesizer 构造函数。
cosyvoice-v3-flash:
通过
影响首包延迟的因素:
在单向流式或双向流式调用中通过
服务端返回二进制音频数据:
更多示例请参见 GitHub。
服务端点
SDK 默认服务端点为 wss://dashscope.aliyuncs.com/api-ws/v1/inference。如需修改,可在初始化前设置 Constants.baseWebsocketApiUrl。
前提条件
- 登录千问云并创建 API Key。建议将其导出为环境变量,避免硬编码。
如需向第三方应用提供临时访问权限,或对敏感操作进行严格管控,可使用临时认证令牌。临时令牌 60 秒后过期,可有效降低泄露风险。在代码中用临时令牌替换 API Key 即可。
模型与计费
请参见语音合成。
文本与格式限制
文本长度限制
字符计数规则
- 中文汉字(简体、繁体、日文汉字、韩文汉字)每个计 2 个字符。其他字符(标点、字母、数字、假名、韩文字母)每个计 1 个字符。
- SSML 标签不计入文本长度。
- 示例:
"你好"→ 2(汉字)+ 2(汉字)= 4 字符"中A文123"→ 2(汉字)+ 1(A)+ 2(汉字)+ 1(1)+ 1(2)+ 1(3)= 8 字符"中文。"→ 2(汉字)+ 2(汉字)+ 1(句号)= 5 字符"中 文。"→ 2(汉字)+ 1(空格)+ 2(汉字)+ 1(句号)= 6 字符"<speak>你好</speak>"→ 2(汉字)+ 2(汉字)= 4 字符
编码格式
使用 UTF-8 编码。
数学表达式
cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持数学表达式解析,覆盖常见的中小学数学内容,包括基本运算、代数和几何。
该功能仅支持中文。
SSML 支持
SSML 适用于 cosyvoice-v3-flash 和 cosyvoice-v3-plus 上的自定义音色(声音设计或声音克隆),以及音色列表中标注支持 SSML 的系统音色。
使用要求:
- DashScope SDK 2.20.3 或更高版本。
- 仅支持非流式和单向流式调用(SpeechSynthesizer 的
call方法)。不支持双向流式调用(streamingCall)和 Flowable 调用。 - 将包含 SSML 的文本传给
call方法即可,用法与普通文本相同。
快速开始
SpeechSynthesizer 类支持以下调用方式:
- 非流式:发送完整文本,返回完整音频。阻塞式调用,适合短文本。
- 单向流式:发送完整文本,通过回调返回音频。非阻塞式调用,适合对延迟敏感的短文本场景。
- 双向流式:逐步发送文本片段,通过回调实时返回音频。非阻塞式调用,适合对延迟敏感的长文本场景。
非流式调用
同步发送文本,返回完整音频结果。
call 方法获取二进制音频数据。文本上限:20,000 字符。
每次调用
call 前需重新初始化 SpeechSynthesizer 实例。点击查看完整示例
点击查看完整示例
单向流式调用
异步提交文本,通过 ResultCallback 增量接收音频数据。
call 方法。通过 onEvent 实时获取音频。文本上限:20,000 字符。
每次调用
call 前需重新初始化 SpeechSynthesizer 实例。点击查看完整示例
点击查看完整示例
双向流式调用
分多次发送文本片段,通过 ResultCallback 增量接收音频。
-
多次调用
streamingCall提交文本片段。服务端自动分句:完整句子立即合成,不完整的句子会缓存直到补全。调用streamingComplete()可强制合成所有缓存文本。 -
文本片段发送间隔不得超过 23 秒,否则会触发超时错误。发送完毕后请调用
streamingComplete()。23 秒的服务端超时不可在客户端修改。
1
实例化 SpeechSynthesizer
实例化 SpeechSynthesizer,绑定请求参数和 ResultCallback。
2
发送文本流
多次调用
streamingCall 分段发送文本。服务端通过 onEvent 实时返回音频。每次 streamingCall 的文本片段上限:20,000 字符。所有片段累计上限:200,000 字符。3
完成合成
调用
streamingComplete 完成合成。该方法会阻塞直到 onComplete 或 onError 触发。务必调用此方法,否则尾部文本可能无法被合成。点击查看完整示例
点击查看完整示例
Flowable 调用
Flowable 是 Apache 2.0 协议下的开源响应式编程框架,详情请参见 Flowable API 文档。使用前请先集成 RxJava 库并了解响应式编程基础。
- 单向流式调用
- 双向流式调用
通过 Flowable 对象的
blockingForEach 方法阻塞获取每个 SpeechSynthesisResult。所有流式数据返回后,也可通过 getAudioFrame 获取完整结果。点击查看完整示例
点击查看完整示例
高并发调用
DashScope Java SDK 使用 OkHttp3 连接池来减少连接开销。请参见高并发管理。
请求参数
通过 SpeechSynthesisParam 的链式方法配置 model、voice 等参数,将配置好的对象传给 SpeechSynthesizer 构造函数。
点击查看示例
点击查看示例
| 参数 | 类型 | 是否必选 | 说明 |
|---|---|---|---|
| model | String | 是 | 语音合成模型。所有可选项请参见音色列表。 |
| voice | String | 是 | 合成使用的音色。可用的系统音色请参见音色列表。 |
| format | enum | 否 | 音频格式和采样率。默认:22.05 kHz 的 MP3。默认采样率为音色最佳采样率,支持降采样和升采样。 支持的格式:
|
| volume | int | 否 | 音量。默认:50。范围:[0, 100]。线性缩放,0 为静音,100 为最大音量。 |
| speechRate | float | 否 | 语速。默认:1.0。范围:[0.5, 2.0]。小于 1.0 语速减慢,大于 1.0 语速加快。 |
| pitchRate | float | 否 | 音调倍率。默认:1.0。范围:[0.5, 2.0]。与感知音高的关系非线性:大于 1.0 升高音调,小于 1.0 降低音调。建议实际测试以找到合适的值。 |
| bit_rate | int | 否 | Opus 格式的音频比特率(kbps)。默认:32。范围:[6, 510]。 通过 SpeechSynthesisParam 的 parameter 或 parameters 方法设置。请参见下方示例。 |
| enableWordTimestamp | boolean | 否 | 是否启用字级时间戳。默认:false。适用于 cosyvoice-v3-flash、cosyvoice-v3-plus 和 cosyvoice-v2 模型的复刻音色,以及音色列表中标注支持此功能的系统音色。 时间戳结果仅通过回调接口返回。 |
| seed | int | 否 | 随机种子。不同的种子产生不同的合成结果,相同种子和相同参数可复现相同输出。默认:0。范围:[0, 65535]。 |
| languageHints | List | 否 | 合成目标语言。当数字、缩写或符号的发音不准确,或不常见语种需要改善时使用。可选值:zh(中文)、en(英文)、fr(法文)、de(德文)、ja(日文)、ko(韩文)、ru(俄文)、pt(葡萄牙文)、th(泰文)、id(印尼文)、vi(越南文)。注意:此参数为数组,但仅处理第一个元素,请只传入一个值。 |
| instruction | String | 否 | 通过指令控制方言、情感或说话风格。适用于音色列表中标注支持 Instruct 的系统音色。最大长度:100 字符。请参见下方指令示例。 |
| enable_aigc_tag | boolean | 否 | 在音频中添加不可见的 AIGC 标识。设为 true 时,在支持的格式(WAV、MP3、Opus)中嵌入不可见标识。默认:false。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。 |
| aigc_propagator | String | 否 | 设置 AIGC 标识中的 ContentPropagator 字段,用于标识内容传播者。仅在 enable_aigc_tag 为 true 时生效。默认:UID。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。 |
| aigc_propagate_id | String | 否 | 设置 AIGC 标识中的 PropagateID 字段,用于唯一标识一次传播行为。仅在 enable_aigc_tag 为 true 时生效。默认:当前请求 ID。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。 |
| hotFix | ParamHotFix | 否 | 文本热补丁配置。可自定义特定词语的发音或在合成前替换文本。仅 cosyvoice-v3-flash 支持。请参见下方 hotFix 示例。 |
| enable_markdown_filter | boolean | 否 | 合成前移除输入文本中的 Markdown 符号,防止其被朗读。默认:false。仅 cosyvoice-v3-flash 支持。 |
设置 bit_rate
- 使用 parameter()
- 使用 parameters()
设置 enable_aigc_tag
- 使用 parameter()
- 使用 parameters()
设置 aigc_propagator
- 使用 parameter()
- 使用 parameters()
设置 aigc_propagate_id
- 使用 parameter()
- 使用 parameters()
设置 enable_markdown_filter
- 使用 parameter()
- 使用 parameters()
instruction 示例
cosyvoice-v3-flash:
- 克隆音色:可使用任意自然语言指令控制合成效果。 指令示例:
- 系统音色:指令必须使用固定格式。详情请参见音色列表。
hotFix 示例
核心接口
SpeechSynthesizer 类
通过 import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer; 导入。
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public SpeechSynthesizer(SpeechSynthesisParam param, ResultCallback<SpeechSynthesisResult> callback) | param:请求参数。callback:流式调用传 ResultCallback,非流式/Flowable 调用传 null。 | SpeechSynthesizer 实例 | 构造函数。单向流式或双向流式调用时将 callback 设为 ResultCallback;非流式或 Flowable 调用时设为 null。 |
public ByteBuffer call(String text) | text:待合成文本(UTF-8)。 | ByteBuffer 或 null | 将文本(纯文本或 SSML)转换为语音。未设置 callback 时:阻塞直到完成。设置了 callback 时:立即返回 null,结果通过 onEvent 返回。 |
public void streamingCall(String text) | text:待合成文本(UTF-8)。 | 无 | 发送文本进行流式合成。不支持 SSML。可多次调用以分段发送文本,结果通过 onEvent 返回。请参见双向流式调用。 |
public void streamingComplete() throws RuntimeException | 无 | 无 | 结束流式合成。阻塞直到合成完成、会话中断或 10 分钟超时。请参见双向流式调用。 |
public Flowable<SpeechSynthesisResult> callAsFlowable(String text) | text:待合成文本(UTF-8)。 | Flowable<SpeechSynthesisResult> | 将非流式文本输入转为流式语音输出。不支持 SSML。请参见 Flowable 调用。 |
boolean getDuplexApi().close(int code, String reason) | code:WebSocket 关闭码。reason:关闭原因。请参见 The WebSocket Protocol。 | true | 每次任务完成后关闭 WebSocket 连接以防止连接泄漏。连接复用请参见高并发管理。 |
public Flowable<SpeechSynthesisResult> streamingCallAsFlowable(Flowable<String> textStream) | textStream:封装待合成文本的 Flowable。 | Flowable<SpeechSynthesisResult> | 将流式文本输入转为流式语音输出。不支持 SSML。请参见 Flowable 调用。 |
public String getLastRequestId() | 无 | 上一次任务的请求 ID。 | 通过 call、streamingCall、callAsFlowable 或 streamingCallAsFlowable 启动新任务后获取请求 ID。 |
public long getFirstPackageDelay() | 无 | 首包延迟(毫秒)。 | 获取从发送文本到收到首个音频包的时间。请在任务完成后调用。 |
使用须知:
- 每次调用
call前需重新初始化SpeechSynthesizer实例。 - 双向流式调用时务必调用
streamingComplete,否则可能丢失合成语音。
- WebSocket 建连(首次调用)
- 音色加载时间(不同音色有差异)
- 服务负载(高峰时段排队)
- 网络延迟
- 复用连接且音色已加载:约 500 ms
- 首次连接或切换音色:1,500-2,000 ms
- 使用连接池预建连接(高并发场景)。
- 检查网络质量。
- 避开高峰时段。
ResultCallback 接口
在单向流式或双向流式调用中通过 ResultCallback 获取合成结果。通过 import com.alibaba.dashscope.common.ResultCallback; 导入。
点击查看示例
点击查看示例
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public void onEvent(SpeechSynthesisResult result) | result:SpeechSynthesisResult 实例。 | 无 | 服务端推送音频数据时触发。通过 SpeechSynthesisResult 的 getAudioFrame 获取二进制音频,通过 getUsage 获取当前已计费字符数。 |
public void onComplete() | 无 | 无 | 所有合成数据返回后触发。 |
public void onError(Exception e) | e:异常信息。 | 无 | 发生异常时触发。请在此方法中实现异常日志记录和资源清理。 |
响应
服务端返回二进制音频数据:
SpeechSynthesisResult 核心接口:
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public ByteBuffer getAudioFrame() | 无 | 二进制音频数据 | 返回当前片段的二进制音频。如果没有新数据则可能为空。可将多个片段拼接为完整文件,也可使用流式播放器逐段播放。 |
public String getRequestId() | 无 | 请求 ID | 获取任务请求 ID。当 getAudioFrame 返回数据时,此方法返回 null。 |
public SpeechSynthesisUsage getUsage() | 无 | SpeechSynthesisUsage 或 null | 通过 getCharacters() 返回当前已计费字符数。以最后一次收到的值为准。 |
public Sentence getTimestamp() | 无 | Sentence 或 null | 当 enableWordTimestamp 为 true 时返回时间戳数据。Sentence 方法:getBeginTime(句子开始时间,ms)、getEndTime(句子结束时间,ms)、getWords(返回 List<Word>)。Word 方法:getText、getBeginIndex、getEndIndex、getBeginTime、getEndTime、getPhonemes(返回 List<Phoneme>,可能为空)。Phoneme 方法:getBeginTime、getEndTime、getText、getTone(音调:英文中 0/1/2 分别为轻音/重音/次重音;拼音中 1-5 分别为一声至轻声)。 |
流式合成使用压缩格式(MP3、Opus)时,请使用流式播放器。逐帧播放会导致解码失败。常用的流式播放器包括 FFmpeg、PyAudio(Python)、AudioFormat(Java)和 MediaSource(JavaScript)。拼接音频为完整文件时,请使用追加模式写入。WAV 和 MP3 流式音频中,仅首帧包含头信息。