本文介绍非实时语音合成Qwen-Audio-TTS的Java SDK调用方法,支持非流式和流式两种调用模式。
前提条件
- 已获取与配置 API Key并将其配置到环境变量
- 已安装符合版本要求的DashScope Java SDK,建议安装最新版,SDK版本需≥2.22.15
HttpSpeechSynthesizer 类
包路径:com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesizer
功能:基于HTTP的语音合成,支持非流式和流式两种调用方式。
构造方法
DASHSCOPE_API_KEY或Constants.apiKey获取API Key。
callAndReturnAudio() - 非流式调用(返回音频数据)
方法签名:
| 参数 | 类型 | 说明 |
|---|---|---|
param | HttpSpeechSynthesisParam | 语音合成参数对象,包含模型、文本、音色等配置。 |
ByteBuffer,包含完整的音频数据。可通过remaining()获取音频大小(字节)。
call() - 非流式调用(返回音频URL)
方法签名:
| 参数 | 类型 | 说明 |
|---|---|---|
param | HttpSpeechSynthesisParam | 语音合成参数对象。 |
HttpSpeechSynthesisResult对象,通过getAudioInfo().getUrl()获取音频下载URL,URL有效期有限,可通过getAudioInfo().getExpiresAt()获取过期时间。
streamCall() - 流式调用
方法签名:
| 参数 | 类型 | 说明 |
|---|---|---|
param | HttpSpeechSynthesisParam | 语音合成参数对象。 |
callback | ResultCallback<HttpSpeechSynthesisResult> | 回调对象,需实现onEvent(接收音频分片)、onComplete(合成完成)、onError(错误处理)三个方法。 |
com.alibaba.dashscope.common.ResultCallback是DashScope SDK提供的通用回调接口,需实现以下三个方法:
| 方法 | 参数 | 说明 |
|---|---|---|
onEvent | HttpSpeechSynthesisResult result | 每接收到一个音频分片时触发。通过result.hasAudioData()判断是否包含音频数据,通过result.getAudioDataSize()获取分片大小。 |
onComplete | 无 | 语音合成完成时触发,表示所有音频分片已接收完毕。 |
onError | Exception e | 合成过程中发生错误时触发,可通过e.getMessage()获取错误信息。 |
HttpSpeechSynthesisParam 类
包路径:com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisParam
通过Builder模式构建参数对象。
部分参数没有专用的Builder方法,需要通过继承自父类的parameter(String key, Object value)方法或parameters(Map<String, Object>)方法进行设置,详见下表中的说明。
| 方法 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model(String) | String | 是 | 语音合成模型。 |
| text(String) | String | 是 | 待合成文本。 支持 SSML 和 LaTeX 格式输入。将待合成文本替换为对应格式即可。
|
| voice(String) | String | 是 | 音色。 取值范围:
|
| format(String) | String | 否 | 音频编码格式。 默认值:mp3。 取值范围:
|
| sampleRate(int) | int | 否 | 音频采样率(Hz)。 取值范围:8000, 16000, 22050(默认), 24000, 44100, 48000。 |
| volume(int) | int | 否 | 音量。 默认值:50。 取值范围:[0, 100]。 |
| rate(float) | float | 否 | 语速。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
| pitch(float) | float | 否 | 音调。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
enable_ssml | boolean | 否 | 是否开启SSML功能。设置为true时,text参数需传入SSML格式文本。支持的SSML标签及用法,请参见SSML 与 LaTeX。SSML 的使用限制(支持的模型、音色和接口),请参见使用限制。 默认值:false。 enable_ssml需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 1 请参见表格下方 示例 2 请参见表格下方 |
word_timestamp_enabled | boolean | 否 | 是否开启字级别时间戳。 默认值:false。 仅在流式输出模式下可用。支持复刻音色;支持的系统音色请参见Qwen-Audio-TTS音色列表。 word_timestamp_enabled需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 3 请参见表格下方 示例 4 请参见表格下方 |
seed | int | 否 | 生成时使用的随机数种子,使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下,使用相同的seed可复现相同的合成结果。 默认值0。 取值范围:[0, 65535]。 seed需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 5 请参见表格下方 示例 6 请参见表格下方 |
language_hints | List | 否 | 提示: - 此参数为数组,但当前版本仅处理第一个元素,因此建议只传入一个值。
language_hints需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 7 请参见表格下方 示例 8 请参见表格下方 |
instruction | String | 否 | 设置指令,用于控制方言、情感或角色等合成效果。 具体用法请参见非实时语音合成。 instruction需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 9 请参见表格下方 示例 10 请参见表格下方 |
bit_rate | int | 否 | 音频码率(单位:kbps)。 默认值:32。 取值范围:[6, 510]。 提示: 仅在format为opus时支持使用该参数。 bit_rate需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 11 请参见表格下方 示例 12 请参见表格下方 |
enable_aigc_tag | boolean | 否 | 是否在生成的音频中添加AIGC隐性标识。设置为true时,会将隐性标识嵌入到支持格式(wav/mp3/opus)的音频中。 默认值:false。 enable_aigc_tag需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 13 请参见表格下方 示例 14 请参见表格下方 |
aigc_propagator | String | 否 | 设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。 默认值:千问AI平台账号。 aigc_propagator需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 15 请参见表格下方 示例 16 请参见表格下方 |
aigc_propagate_id | String | 否 | 设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。 默认值:本次语音合成请求Request ID。 aigc_propagate_id需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 17 请参见表格下方 示例 18 请参见表格下方 |
hot_fix | Map | 否 | 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。 参数介绍:
hot_fix需要通过HttpSpeechSynthesisParam实例的parameter方法或者parameters方法进行设置: 示例 20 请参见表格下方 示例 21 请参见表格下方 |
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
通过parameter设置
通过parameters设置
示例代码
以下示例展示Qwen-Audio-TTS语音合成的非流式和流式调用方式。运行前请确保已设置环境变量DASHSCOPE_API_KEY。
不同模型需使用匹配的音色。更换模型时,请同步更换音色,并确认音色支持目标语言。具体对应关系请参见Qwen-Audio-TTS音色列表。