本文介绍语音合成Sambert Python SDK的参数和接口细节。
用户指南:关于模型介绍和选型建议请参见实时语音合成-CosyVoice /Sambert。
在线体验:暂不支持。
重要阿里云百炼为华北2(北京)地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。
{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。
前提条件
已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
快速开始
核心资源(client.audio.tts)提供了非流式调用和单向流式调用的接口。请根据业务场景选择合适的调用方式:
- 非流式调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本合成场景。
- 单向流式调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的场景。
非流式调用
提交单个语音合成任务,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。
直接调用核心资源(client.audio.tts)的synthesize方法进行语音合成。synthesize方法可对请求参数进行设置。
任务完成后该方法返回完整的音频数据(bytes,时间戳信息需通过流式会话获取,参见响应结果)。
点击查看完整示例
以下示例展示了如何使用同步接口调用发音人模型知厨(sambert-zhichu-v1),将文案”今天天气怎么样”合成采样率为48kHz,音频格式为wav的音频,并保存到名为output.wav的文件中。
# coding=utf-8
import os
import sys
import dashscope
# 若没有将API Key配置到环境变量中,需将下行替换为自己的API Key:api_key="sk-xxx"
# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
audio = client.audio.tts.synthesize(
'今天天气怎么样',
model='sambert-zhichu-v1',
sample_rate=48000,
format='wav')
with open('output.wav', 'wb') as f:
f.write(audio)
print('SUCCESS: get audio data: %dbytes in output.wav' % (sys.getsizeof(audio)))
单向流式调用
提交单个语音合成任务,流式输出中间结果,合成结果通过流式合成会话的events()/audio_chunks()迭代获取。
- 调用核心资源(
client.audio.tts)的connect方法创建流式合成会话,进入with上下文时自动建立连接。 - 调用会话的
send_text方法发送待合成文本,stop方法通知服务端输入结束。 - 在接收线程中迭代会话的
events()(音频bytes与JSON事件,含时间戳)或audio_chunks()(仅音频)获取合成结果。
点击查看完整示例
以下示例展示了如何使用流式接口调用发音人模型知厨(sambert-zhichu-v1)将文案”今天天气怎么样”合成采样率为48kHz,默认音频格式(wav)的流式音频,并获取对应时间戳。
# coding=utf-8
import os
import sys
import dashscope
# 若没有将API Key配置到环境变量中,需将下行替换为自己的API Key:api_key="sk-xxx"
# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
# 创建流式合成会话:进入 with 上下文时自动建立连接
with client.audio.tts.connect(
model='sambert-zhichu-v1',
sample_rate=48000,
parameters={'word_timestamp_enabled': True,
'phoneme_timestamp_enabled': True},
) as session:
session.send_text('今天天气怎么样')
# 通知服务端输入结束
session.stop()
# events() 同时产出音频 bytes 与服务端 JSON 事件(含时间戳)
for event in session.events():
if isinstance(event, bytes):
print('audio result length:', sys.getsizeof(event))
else:
output = (event.get('payload') or {}).get('output') or {}
if output.get('timestamp') is not None:
print('timestamp result:', str(output.get('timestamp')))
请求参数
请求参数通过核心资源(client.audio.tts)的synthesize/stream/connect方法进行设置(具名参数直接传入,word_timestamp_enabled、phoneme_timestamp_enabled通过parameters字典传入)。
| 参数 | 类型 | 默认值 | 是否必须 | 说明 |
|---|---|---|---|---|
model | str | 是 | 指定用于语音合成的音色模型名,完整列表参见模型列表。 | |
text | str | 是 | 指定待合成文本,要求采用UTF-8编码且不能为空。 最高字符限制:1万字符。
支持SSML格式。SSML标记语言的使用请参见SSML标记语言介绍。 | |
format | str | wav | 否 | 指定合成音频的编码格式,支持 |
sample_rate | int | 16000 | 否 | 指定合成音频的采样率(单位:Hz),建议使用模型默认采样率(参见模型列表),如果不匹配,服务会进行必要的升降采样处理。 |
volume | int | 50 | 否 | 指定合成音频的音量,取值范围是0~100。 |
rate | float | 1.0 | 否 | 指定合成音频的语速,取值范围:0.5~2。
|
pitch | float | 1.0 | 否 | 指定合成音频的语调,取值范围:0.5~2。 |
word_timestamp_enabled | bool | False | 否 | 是否开启字级别时间戳。默认不开启。 |
phoneme_timestamp_enabled | bool | False | 否 | 在开启字级别时间戳( |
关键接口
核心资源(client.audio.tts)
语音合成能力挂载在client.audio.tts资源上:synthesize一次性返回完整音频,stream流式产出音频分片,connect创建流式合成会话。它的关键接口如下:
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 完整的音频数据( | 开启语音合成任务,在语音合成完成后返回完整音频数据。
| |
| 同 | 逐块产出的音频数据( | 开启语音合成任务,一次性发送文本并逐块产出音频分片。只输出音频,不暴露逐条JSON元数据(需时间戳请使用 |
|
| 创建流式合成会话,进入 |
事件迭代(events()/audio_chunks())
单向流式调用时,服务端会通过事件的方式,将关键流程信息和数据返回给客户端。在接收线程中迭代会话的events()或audio_chunks()处理服务端返回的信息或者数据。
点击查看示例
# events() 同时产出音频 bytes 与服务端 JSON 事件(含时间戳)
for event in session.events():
if isinstance(event, bytes):
print('收到二进制音频数据:', event)
else:
output = (event.get('payload') or {}).get('output') or {}
if output.get('timestamp') is not None:
print('收到时间戳数据:', str(output.get('timestamp')))
# 或只迭代音频(仍更新会话的 last_response 与 usage)
for chunk in session.audio_chunks():
print('收到二进制音频数据:', chunk)
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
|
| 无 | 发送待合成文本。发送文本与接收结果需并发进行。 |
| 无 | 无 | 通知服务端输入结束,之后继续消费 |
| 无 |
| 当服务端返回合成数据时逐个产出:音频为 |
| 无 |
| 只迭代音频数据,仍更新会话的 |
| 无 |
| 从发送文本到收到第一块音频数据的延迟时间(毫秒),任务完成后读取。 |
响应结果
合成结果(音频数据与时间戳)
synthesize返回完整的音频bytes;流式调用通过stream或会话的audio_chunks()逐块接收音频bytes;时间戳信息通过会话events()产出的JSON事件获取(payload.output.timestamp)。
| 接口/方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 无 | 完整的二进制音频数据 | 非流式合成中,获取完整的二进制音频数据。 |
| 无 | 当前合成的二进制音频数据片段 | 流式合成中,逐块接收当前合成的音频帧数据。 |
| 无 | 当前合成的句子对应的时间戳信息 | 流式合成中,从 |
| 无 | 所有句子对应的时间戳信息 | 流式合成中,累积 |
时间戳信息
会话events()产出的JSON事件中,payload.output.timestamp为当前合成的句子的时间戳信息,累积各句即为所有句子的时间戳信息。
单个句子的时间戳信息示例如下所示,其中words对应的是字级别时间戳信息。phonemes对应的是音素级别时间戳信息:
{
"begin_time":0,
"end_time":1412,
"words":[
{
"text":"今",
"begin_time":0,
"end_time":200,
"phonemes":[
{
"begin_time":0,
"end_time":82,
"text":"j_c",
"tone":1
},
{
"begin_time":82,
"end_time":200,
"text":"in_c",
"tone":1
}
]
}
]
}
各参数含义如下所示:
参数 | 类型 | 说明 |
|---|---|---|
begin_time | int | 句子、字、音素开始时间,单位为ms。 |
end_time | int | 句子、字、音素结束时间,单位为ms。 |
words | list | 包含的字级别时间戳信息,需要请求中 |
text | str | 文本信息。 |
phonemes | list | 包含的音素级别时间戳信息,需要请求中 |
tone | str | 音调。
|
错误码
在使用API过程中,如果调用失败并返回错误信息,请参见错误码进行解决。
更多示例
更多示例,请参见GitHub。
常见问题
请参见GitHub QA。
模型列表
说明默认采样率代表当前模型的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如知妙音色,默认采样率16 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。
| 音色 | 音频试听(右键保存音频) | 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 |