本文介绍语音合成Sambert Java API的使用。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
调用模式
核心类(SpeechSynthesizer)提供了同步调用和流式调用的接口。请根据业务场景选择合适的调用模式。
同步调用
提交单个语音合成任务,无需调用回调方法,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。
配置请求参数。
设置模型、待合成文本等参数:
SpeechSynthesisParam param = SpeechSynthesisParam.builder() .model("sambert-zhichu-v1") .text("今天天气怎么样") .sampleRate(48000) .format(SpeechSynthesisAudioFormat.WAV) .build();
-
SpeechSynthesizer synthesizer = new SpeechSynthesizer();
同步调用。
调用核心类(SpeechSynthesizer)的
call
方法,该方法阻塞当前线程直到所有结果返回,返回的数据类型为ByteBuffer
类型。// 提交同步合成任务,获取完整的音频数据 ByteBuffer audio = synthesizer.call(param);
处理音频数据。
处理音频数据,例如保存到本地。
流式调用
提交单个语音合成任务,通过回调的方式流式输出中间结果,合成结果通过ResultCallback
中的回调方法流式进行获取。
配置请求参数。
设置模型、待合成文本等参数:
SpeechSynthesisParam param = SpeechSynthesisParam.builder() .model("sambert-zhichu-v1") .text("今天天气怎么样") .sampleRate(48000) .format(SpeechSynthesisAudioFormat.WAV) .build();
-
SpeechSynthesizer synthesizer = new SpeechSynthesizer();
开启任务,流式接收合成结果。
调用核心类(SpeechSynthesizer)的
call
方法开启任务。语音合成的结果通过回调接口(ResultCallback)的回调方法(如onEvent
、onComplete
)实时返回并处理。synthesizer.call(param, callback);
文本提交完成后结束任务。
调用核心类(SpeechSynthesizer)的
streamingComplete
方法结束任务,请勿遗漏该步骤,否则服务端可能不会返回缓存的剩余音频数据。语音合成成功完成回调后(
ResultCallback
的onComplete
方法被调用之后)还可以一次性获取完整的音频和时间戳结果(调用核心类(SpeechSynthesizer)的getAudioData
和getTimestamps
方法)。synthesizer.streamingComplete();
通过Flowable调用
Flowable是一个用于工作流和业务流程管理的开源框架,它基于Apache 2.0许可证发布。关于Flowable的使用,请参见Flowable API详情。
高并发调用
在DashScope Java SDK中,采用了OkHttp3的连接池技术,以减少重复建立连接的开销。详情请参见高并发场景。
请求参数
请求参数通过SpeechSynthesisParam
的链式方法进行配置。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | String | - | 是 | 指定用于语音合成的音色模型名,完整列表请参见模型列表。 |
text | String | - | 是 | 指定待合成文本,要求采用UTF-8编码且不能为空。 最高字符限制:1万字符。 字符计算规则:1个汉字、1个英文字母、1个标点或1个句子中间空格均算作1个字符。 支持SSML格式。SSML标记语言的使用请参见SSML标记语言介绍。 |
format | enum | SpeechSynthesisAudioFormat.WAV | 否 | 指定合成音频的编码格式,支持下列格式:
|
sampleRate | int | 16000 | 否 | 指定合成音频的采样率(单位:Hz),建议使用模型默认采样率(参见模型列表),如果不匹配,服务会进行必要的升降采样处理。 |
volume | int | 50 | 否 | 指定合成音频的音量,取值范围是0~100。 |
rate | float | 1.0 | 否 | 指定合成音频的语速,取值范围:0.5~2。
|
pitch | float | 1.0 | 否 | 指定合成音频的语调,取值范围:0.5~2。 |
enableWordTimestamp | boolean | false | 否 | 是否开启字级别时间戳。默认不开启。 |
enablePhonemeTimestamp | boolean | false | 否 | 是否在开启字级别时间戳( |
apiKey | String | - | 否 | 用户API Key。如已将API Key配置到环境变量,则无须在代码中设置。 |
响应结果
同步调用模式:响应结果为二进制音频数据。
流式调用模式:响应结果为音频数据和时间戳信息(SpeechSynthesisResult)。
音频数据和时间戳信息(SpeechSynthesisResult
)
SpeechSynthesisResult
封装了语音合成结果,常用的接口为getAudioFrame
和getTimestamp
。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 二进制音频数据 | 返回一个流式合成片段的增量二进制音频数据,可能为空。 |
| 无 | 句子级别时间戳信息(Sentence)的 | 批量获取句子级别时间戳信息,可能为空。 |
句子级别时间戳信息(Sentence
)
Sentence
封装了句子级别时间戳信息。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 句子开始时间,单位为ms | 返回句子开始时间。 |
| 无 | 句子结束时间,单位为ms | 返回句子结束时间。 |
| 无 | 字级别时间戳信息(Word)的 | 批量获取字级别时间戳信息,可能为空。 |
字级别时间戳信息(Word
)
Word
封装了字级别时间戳信息。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 词开始时间,单位为ms | 返回词开始时间。 |
| 无 | 词结束时间,单位为ms | 返回词结束时间。 |
| 无 | 文本信息 | 返回文本信息。 |
| 无 | 音素级别时间戳信息(Phoneme)的 | 批量获取音素级别时间戳信息,可能为空。 |
音素级别时间戳信息(Phoneme
)
Phoneme
封装了音素级别时间戳信息。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 音素开始时间,单位为ms | 返回音素开始时间。 |
| 无 | 音素结束时间,单位为ms | 返回音素结束时间。 |
| 无 | 文本信息 | 返回文本信息。 |
| 无 | 音调 | 返回音调。
|
关键接口
回调接口(ResultCallback
)
实现异步监听需继承ResultCallback
抽象类,具备以下特征:
类型化处理:通过泛型
SpeechSynthesisResult
处理结构化数据。事件驱动:专注处理有效业务数据,需实现以下方法:
onEvent(SpeechSynthesisResult result)
:接收实时音频分片(可能为空,参见音频数据和时间戳信息(SpeechSynthesisResult))。onComplete()
:任务成功完成时回调。onError(Exception e)
:异常处理,建议记录日志并释放资源。
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 当服务端返回合成数据时会被回调。 | |
| 无 | 无 | 当所有合成数据全部返回后被回调。 |
|
| 无 | 当调用过程出现异常以及服务返回错误后被回调。 |
核心类(SpeechSynthesizer
)
SpeechSynthesizer
可以通过“import com.alibaba.dashscope.audio.tts.SpeechSynthesizer;
”方式引入。它的关键接口如下:
接口/方法 | 参数 | 返回值 | 描述 |
接口/方法 | 参数 | 返回值 | 描述 |
|
| 二进制音频 | 发送待合成文本并获取语音合成结果。该方法阻塞当前线程直到所有结果返回。 |
|
| 无 | 异步开启语音合成任务。 任务开启后,服务端会通过回调的方式调用 |
| 无 | 二进制音频 | 获取完整的二进制音频数据。 流式调用时,完成回调后( |
| 无 | 句子级别时间戳信息(Sentence)的 | 获取完整的句子级别时间戳信息(Sentence)。 流式调用时,完成回调后( |
| 无 | 当前任务的request ID | 获取当前任务的request ID,在调用 |
| 无 | 当前任务首包延迟 | 获取当前任务的首包延迟,任务结束后使用。 |
错误码
在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。
更多示例
更多示例,请参见GitHub。
常见问题
请参见GitHub QA。
模型列表
默认采样率代表当前模型的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如知妙音色,默认采样率16 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。
音色 | 音频试听 | model参数 | 时间戳支持 | 适用场景 | 特色 | 语言 | 默认采样率(Hz) |
音色 | 音频试听 | model参数 | 时间戳支持 | 适用场景 | 特色 | 语言 | 默认采样率(Hz) |
知楠 | sambert-zhinan-v1 | 是 | 通用场景 | 广告男声 | 中文+英文 | 48k | |
知琪 | sambert-zhiqi-v1 | 是 | 通用场景 | 温柔女声 | 中文+英文 | 48k | |
知厨 | sambert-zhichu-v1 | 是 | 新闻播报 | 舌尖男声 | 中文+英文 | 48k | |
知德 | sambert-zhide-v1 | 是 | 新闻播报 | 新闻男声 | 中文+英文 | 48k | |
知佳 | sambert-zhijia-v1 | 是 | 新闻播报 | 标准女声 | 中文+英文 | 48k | |
知茹 | sambert-zhiru-v1 | 是 | 新闻播报 | 新闻女声 | 中文+英文 | 48k | |
知倩 | sambert-zhiqian-v1 | 是 | 配音解说、新闻播报 | 资讯女声 | 中文+英文 | 48k | |
知祥 | sambert-zhixiang-v1 | 是 | 配音解说 | 磁性男声 | 中文+英文 | 48k | |
知薇 | sambert-zhiwei-v1 | 是 | 阅读产品简介 | 萝莉女声 | 中文+英文 | 48k | |
知浩 | sambert-zhihao-v1 | 是 | 通用场景 | 咨询男声 | 中文+英文 | 16k | |
知婧 | sambert-zhijing-v1 | 是 | 通用场景 | 严厉女声 | 中文+英文 | 16k | |
知茗 | sambert-zhiming-v1 | 是 | 通用场景 | 诙谐男声 | 中文+英文 | 16k | |
知墨 | sambert-zhimo-v1 | 是 | 通用场景 | 情感男声 | 中文+英文 | 16k | |
知娜 | sambert-zhina-v1 | 是 | 通用场景 | 浙普女声 | 中文+英文 | 16k | |
知树 | sambert-zhishu-v1 | 是 | 通用场景 | 资讯男声 | 中文+英文 | 16k | |
知莎 | sambert-zhistella-v1 | 是 | 通用场景 | 知性女声 | 中文+英文 | 16k | |
知婷 | sambert-zhiting-v1 | 是 | 通用场景 | 电台女声 | 中文+英文 | 16k | |
知笑 | sambert-zhixiao-v1 | 是 | 通用场景 | 资讯女声 | 中文+英文 | 16k | |
知雅 | sambert-zhiya-v1 | 是 | 通用场景 | 严厉女声 | 中文+英文 | 16k | |
知晔 | sambert-zhiye-v1 | 是 | 通用场景 | 青年男声 | 中文+英文 | 16k | |
知颖 | sambert-zhiying-v1 | 是 | 通用场景 | 软萌童声 | 中文+英文 | 16k | |
知媛 | sambert-zhiyuan-v1 | 是 | 通用场景 | 知心姐姐 | 中文+英文 | 16k | |
知悦 | sambert-zhiyue-v1 | 是 | 客服 | 温柔女声 | 中文+英文 | 16k | |
知柜 | sambert-zhigui-v1 | 是 | 阅读产品简介 | 直播女声 | 中文+英文 | 16k | |
知硕 | sambert-zhishuo-v1 | 是 | 数字人 | 自然男声 | 中文+英文 | 16k | |
知妙(多情感) | sambert-zhimiao-emo-v1 | 是 | 阅读产品简介、数字人、直播 | 多种情感女声 | 中文+英文 | 16k | |
知猫 | sambert-zhimao-v1 | 是 | 阅读产品简介、配音解说、数字人、直播 | 直播女声 | 中文+英文 | 16k | |
知伦 | sambert-zhilun-v1 | 是 | 配音解说 | 悬疑解说 | 中文+英文 | 16k | |
知飞 | sambert-zhifei-v1 | 是 | 配音解说 | 激昂解说 | 中文+英文 | 16k | |
知达 | sambert-zhida-v1 | 是 | 新闻播报 | 标准男声 | 中文+英文 | 16k | |
Camila | sambert-camila-v1 | 否 | 通用场景 | 西班牙语女声 | 西班牙语 | 16k | |
Perla | sambert-perla-v1 | 否 | 通用场景 | 意大利语女声 | 意大利语 | 16k | |
Indah | sambert-indah-v1 | 否 | 通用场景 | 印尼语女声 | 印尼语 | 16k | |
Clara | sambert-clara-v1 | 否 | 通用场景 | 法语女声 | 法语 | 16k | |
Hanna | sambert-hanna-v1 | 否 | 通用场景 | 德语女声 | 德语 | 16k | |
Beth | sambert-beth-v1 | 是 | 通用场景 | 咨询女声 | 美式英文 | 16k | |
Betty | sambert-betty-v1 | 是 | 通用场景 | 客服女声 | 美式英文 | 16k | |
Cally | sambert-cally-v1 | 是 | 通用场景 | 自然女声 | 美式英文 | 16k | |
Cindy | sambert-cindy-v1 | 是 | 通用场景 | 对话女声 | 美式英文 | 16k | |
Eva | sambert-eva-v1 | 是 | 通用场景 | 陪伴女声 | 美式英文 | 16k | |
Donna | sambert-donna-v1 | 是 | 通用场景 | 教育女声 | 美式英文 | 16k | |
Brian | sambert-brian-v1 | 是 | 通用场景 | 客服男声 | 美式英文 | 16k | |
Waan | sambert-waan-v1 | 否 | 通用场景 | 泰语女声 | 泰语 | 16k |
- 本页导读 (1)
- 前提条件
- 调用模式
- 同步调用
- 流式调用
- 通过Flowable调用
- 高并发调用
- 请求参数
- 响应结果
- 音频数据和时间戳信息(SpeechSynthesisResult)
- 句子级别时间戳信息(Sentence)
- 字级别时间戳信息(Word)
- 音素级别时间戳信息(Phoneme)
- 关键接口
- 回调接口(ResultCallback)
- 核心类(SpeechSynthesizer)
- 错误码
- 更多示例
- 常见问题
- 模型列表