Skip to main content

Sambert Python SDK

通过 WebSocket 使用 DashScope Python SDK 调用 Sambert。

用户指南:关于模型介绍和选型建议请参见实时语音合成-CosyVoice /Sambert。 在线体验:暂不支持。
阿里云百炼为华北2(北京)地域推出了业务空间专属域名,能够为推理请求提供卓越的性能和更高的稳定性,建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

前提条件

已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。

模型列表

默认采样率代表当前模型的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如知妙音色,默认采样率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
Camilasambert-camila-v1否通用场景西班牙语女声西班牙语16k
Perlasambert-perla-v1否通用场景意大利语女声意大利语16k
Indahsambert-indah-v1否通用场景印尼语女声印尼语16k
Clarasambert-clara-v1否通用场景法语女声法语16k
Hannasambert-hanna-v1否通用场景德语女声德语16k
Bethsambert-beth-v1是通用场景咨询女声美式英文16k
Bettysambert-betty-v1是通用场景客服女声美式英文16k
Callysambert-cally-v1是通用场景自然女声美式英文16k
Cindysambert-cindy-v1是通用场景对话女声美式英文16k
Evasambert-eva-v1是通用场景陪伴女声美式英文16k
Donnasambert-donna-v1是通用场景教育女声美式英文16k
Briansambert-brian-v1是通用场景客服男声美式英文16k
Waansambert-waan-v1否通用场景泰语女声泰语16k

快速开始

核心资源(client.audio.tts)提供了非流式调用和单向流式调用的接口。请根据业务场景选择合适的调用方式:
  • 非流式调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本合成场景。
  • 单向流式调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的场景。

非流式调用

提交单个语音合成任务,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。
image
直接调用核心资源(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()迭代获取。
image
  1. 调用核心资源(client.audio.tts)的connect方法创建流式合成会话,进入with上下文时自动建立连接。
  2. 调用会话的send_text方法发送待合成文本,stop方法通知服务端输入结束。
  3. 在接收线程中迭代会话的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字典传入)。
参数类型默认值是否必须说明
modelstr
是指定用于语音合成的音色模型名,完整列表参见模型列表。
textstr
是指定待合成文本,要求采用UTF-8编码且不能为空。最高字符限制:1万字符。
字符计算规则:1个汉字、1个英文字母、1个标点或1个句子中间空格均算作1个字符。
支持SSML格式。SSML标记语言的使用请参见SSML标记语言介绍。
formatstrwav否指定合成音频的编码格式,支持pcm、wav和mp3这三种格式。
sample_rateint16000否指定合成音频的采样率(单位:Hz),建议使用模型默认采样率(参见模型列表),如果不匹配,服务会进行必要的升降采样处理。
volumeint50否指定合成音频的音量,取值范围是0~100。
ratefloat1.0否指定合成音频的语速,取值范围:0.5~2。
  • 0.5:表示默认语速的0.5倍速。
  • 1:表示默认语速。默认语速是指模型默认输出的合成语速,语速会因发音人不同而略有不同。约每秒钟4个字。
  • 2:表示默认语速的2倍速。
pitchfloat1.0否指定合成音频的语调,取值范围:0.5~2。
word_timestamp_enabledboolFalse否是否开启字级别时间戳。默认不开启。
phoneme_timestamp_enabledboolFalse否在开启字级别时间戳(word_timestamp_enabled)的基础上,生成音素级别时间戳信息。默认不开启。

接口参考

核心资源(client.audio.tts)

语音合成能力挂载在client.audio.tts资源上:synthesize一次性返回完整音频,stream流式产出音频分片,connect创建流式合成会话。它的关键接口如下:
接口/方法参数返回值描述
def synthesize(self,
               text: str,
               *,
               model: str,
               voice: str = "longxiaochun",
               format: str = "mp3",
               sample_rate: int = 22050,
               volume: int = None,
               rate: float = None,
               pitch: float = None,
               parameters: Dict = None,
               ...) -> bytes
完整的音频数据(bytes)开启语音合成任务,在语音合成完成后返回完整音频数据。synthesize方法能够对请求参数进行设置。
def stream(self,
           text: str,
           *,
           model: str,
           ...) -> Iterator[bytes]
同synthesize逐块产出的音频数据(Iterator[bytes])开启语音合成任务,一次性发送文本并逐块产出音频分片。只输出音频,不暴露逐条JSON元数据(需时间戳请使用connect会话)。
def connect(self,
            *,
            model: str,
            format: str = "mp3",
            sample_rate: int = 22050,
            parameters: Dict = None,
            ...) -> SynthesisSession
SynthesisSession流式合成会话创建流式合成会话,进入with上下文时自动建立连接。配合send_text、stop、events()/audio_chunks()使用(见事件迭代)。

事件迭代(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)
接口/方法参数返回值描述
def send_text(self, text: str) -> None
text:待合成文本无发送待合成文本。发送文本与接收结果需并发进行。
def stop(self) -> None
无无通知服务端输入结束,之后继续消费events()/audio_chunks()直到剩余音频全部返回。
def events(self) -> Generator[Union[Dict, bytes], None, None]
无Dict(JSON事件)或bytes(音频)当服务端返回合成数据时逐个产出:音频为bytes帧,元数据(时间戳等)为JSON事件dict。同一会话只允许一个events()或audio_chunks()读取者。
def audio_chunks(self) -> Iterator[bytes]
无bytes只迭代音频数据,仍更新会话的last_response与usage。
session.first_package_delay
无float从发送文本到收到第一块音频数据的延迟时间(毫秒),任务完成后读取。

响应结果

合成结果(音频数据与时间戳)

synthesize返回完整的音频bytes;流式调用通过stream或会话的audio_chunks()逐块接收音频bytes;时间戳信息通过会话events()产出的JSON事件获取(payload.output.timestamp)。
接口/方法参数返回值描述
audio = client.audio.tts.synthesize(...)
无完整的二进制音频数据非流式合成中,获取完整的二进制音频数据。
for chunk in session.audio_chunks():
无当前合成的二进制音频数据片段流式合成中,逐块接收当前合成的音频帧数据。
output = (event.get('payload') or {}).get('output') or {}
output.get('timestamp')
无当前合成的句子对应的时间戳信息流式合成中,从events()产出的JSON事件里获取当前合成的句子对应的时间戳信息。
timestamps = [
    ((e.get('payload') or {}).get('output') or {}).get('timestamp')
    for e in json_events if ...
]
无所有句子对应的时间戳信息流式合成中,累积events()产出的各句时间戳即为所有句子对应的时间戳信息。

时间戳信息

会话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

包含的字级别时间戳信息,需要请求中word_timestamp_enabled也设置为true。

text

str

文本信息。

phonemes

list

包含的音素级别时间戳信息,需要请求中phoneme_timestamp_enabled也设置为true。

tone

str

音调。

  • 英文中,0、1、2分别代表轻音、重音和次重音。

  • 拼音中,1、2、3、4、5分别代表一声、二声、三声、四声和轻声。

更多示例

更多示例,请参见GitHub。

错误码

在使用API过程中,如果调用失败并返回错误信息,请参见错误码进行解决。