语音合成Sambert Python API

更新时间:2025-03-13 02:42:05

本文介绍语音合成Sambert Python API的使用。

前提条件

调用模式

核心类(SpeechSynthesizer)提供了同步调用和流式调用等接口。请根据业务场景选择合适的调用模式。

同步调用

提交单个语音合成任务,无需调用回调接口,进行语音合成(无流式输出中间结果),最终一次性获取完整结果。

image

直接调用核心类(SpeechSynthesizer)call方法进行语音合成。call方法可对请求参数进行设置,注意此时不要设置callback参数。

任务完成后该方法返回音频数据和时间戳信息(SpeechSynthesisResult)

点击查看完整示例

以下示例展示了如何使用同步接口调用发音人模型知厨(sambert-zhichu-v1),将文案“今天天气怎么样”合成采样率为48kHz,音频格式为wav的音频,并保存到名为output.wav的文件中。

# coding=utf-8
import sys
from dashscope.audio.tts import SpeechSynthesizer
# 若没有将API Key配置到环境变量中,需将apiKey替换为自己的API Key
# import dashscope
# dashscope.api_key = "apiKey"
result = SpeechSynthesizer.call(model='sambert-zhichu-v1',
                                text='今天天气怎么样',
                                sample_rate=48000,
                                format='wav')
if result.get_audio_data() is not None:
    with open('output.wav', 'wb') as f:
        f.write(result.get_audio_data())
    print('SUCCESS: get audio data: %dbytes in output.wav' %
          (sys.getsizeof(result.get_audio_data())))
else:
    print('ERROR: response is %s' % (result.get_response()))

流式调用

提交单个语音合成任务,通过回调的方式流式输出中间结果,合成结果通过ResultCallback中的回调方法流式获取。

image
  1. 实例化回调接口(ResultCallback)

  2. 调用核心类(SpeechSynthesizer)call方法进行语音合成。call方法可对请求参数进行设置,注意此时要设置callback参数。

点击查看完整示例

以下示例展示了如何使用流式接口调用发音人模型知厨(sambert-zhichu-v1)将文案“今天天气怎么样”合成采样率为48kHz,默认音频格式(wav)的流式音频,并获取对应时间戳。

# coding=utf-8

import sys
from dashscope.api_entities.dashscope_response import SpeechSynthesisResponse
from dashscope.audio.tts import ResultCallback, SpeechSynthesizer, SpeechSynthesisResult

# 若没有将API Key配置到环境变量中,需将apiKey替换为自己的API Key
# import dashscope
# dashscope.api_key = "apiKey"

class Callback(ResultCallback):
    def on_open(self):
        print('Speech synthesizer is opened.')

    def on_complete(self):
        print('Speech synthesizer is completed.')

    def on_error(self, response: SpeechSynthesisResponse):
        print('Speech synthesizer failed, response is %s' % (str(response)))

    def on_close(self):
        print('Speech synthesizer is closed.')

    def on_event(self, result: SpeechSynthesisResult):
        if result.get_audio_frame() is not None:
            print('audio result length:', sys.getsizeof(result.get_audio_frame()))

        if result.get_timestamp() is not None:
            print('timestamp result:', str(result.get_timestamp()))

callback = Callback()
SpeechSynthesizer.call(model='sambert-zhichu-v1',
                       text='今天天气怎么样',
                       sample_rate=48000,
                       callback=callback,
                       word_timestamp_enabled=True,
                       phoneme_timestamp_enabled=True)

请求参数

请求参数通过核心类(SpeechSynthesizer)call方法进行设置。

参数

类型

默认值

是否必须

说明

参数

类型

默认值

是否必须

说明

model

str

-

指定用于语音合成的音色模型名,完整列表参见模型列表

text

str

-

指定待合成文本,要求采用UTF-8编码且不能为空。

最高字符限制:1万字符。

字符计算规则:1个汉字、1个英文字母、1个标点或1个句子中间空格均算作1个字符。

支持SSML格式。SSML标记语言的使用请参见SSML标记语言介绍

format

str

wav

指定合成音频的编码格式,支持pcmwavmp3这三种格式。

sample_rate

int

16000

指定合成音频的采样率(单位:Hz),建议使用模型默认采样率(参见模型列表),如果不匹配,服务会进行必要的升降采样处理。

volume

int

50

指定合成音频的音量,取值范围是0~100。

rate

float

1.0

指定合成音频的语速,取值范围:0.5~2。

  • 0.5:表示默认语速的0.5倍速。

  • 1:表示默认语速。默认语速是指模型默认输出的合成语速,语速会因发音人不同而略有不同。约每秒钟4个字。

  • 2:表示默认语速的2倍速。

pitch

float

1.0

指定合成音频的语调,取值范围:0.5~2。

word_timestamp_enabled

bool

False

是否开启字级别时间戳。默认不开启。

phoneme_timestamp_enabled

bool

False

在开启字级别时间戳(word_timestamp_enabled)的基础上,生成音素级别时间戳信息。默认不开启。

callback

ResultCallback

-

设置callback参数时,为流式调用模式。

不设置callback参数时,为同步调用模式。

callback的实现请参见回调接口(ResultCallback)

响应结果

音频数据和时间戳信息(SpeechSynthesisResult

SpeechSynthesisResult封装了语音合成结果,常用的接口为get_audio_frameget_timestampget_audio_dataget_timestamps

接口/方法

参数

返回值

描述

接口/方法

参数

返回值

描述

def get_audio_frame(self) -> bytes

当前合成的二进制音频数据片段

流式合成中,获取当前合成的音频帧数据。

重要

该函数要在流式合成时,在回调方法event中使用。

def get_timestamp(self) -> Dict[str, str]

当前合成的句子对应的时间戳信息

流式合成中,获取当前合成的句子对应的时间戳信息。详情请参见时间戳信息

重要

该函数要在流式合成时,在回调方法event中使用。

def get_audio_data(self) -> bytes

完整的二进制音频数据

获取完整的二进制音频数据。

def get_timestamps(self) -> List[Dict[str, str]]

所有句子对应的时间戳信息

获取所有句子对应的时间戳信息。详情请参见时间戳信息

时间戳信息

SpeechSynthesisResultget_timestamp函数获取的是当前合成的句子的时间戳信息,get_timestamps函数获取的是所有句子的时间戳信息。

单个句子的时间戳信息示例如下所示,其中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分别代表一声、二声、三声、四声和轻声。

关键接口

回调接口(ResultCallback

服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。

点击查看示例

class Callback(ResultCallback):
    def on_open(self):
        print('和服务器成功建立连接')

    def on_complete(self):
        print('任务完成')

    def on_error(self, response: SpeechSynthesisResponse):
        print('报错:%s' % (str(response)))

    def on_close(self):
        print('和服务器之间的连接已关闭')

    def on_event(self, result: SpeechSynthesisResult):
        if result.get_audio_frame() is not None:
            print('收到二进制音频数据:', result.get_audio_frame())

        if result.get_timestamp() is not None:
            print('收到时间戳数据:', str(result.get_timestamp()))

callback = Callback()

接口/方法

参数

返回值

描述

接口/方法

参数

返回值

描述

def on_open(self) -> None

当和服务建立连接完成后会立刻被回调。

def on_event(self, result: SpeechSynthesisResult) -> None

result音频数据和时间戳信息(SpeechSynthesisResult)

当服务端返回合成数据时会被回调。

def on_complete(self) -> None

当所有合成数据全部返回后被回调。

def on_error(self, response: SpeechSynthesisResponse)

response:异常信息

当调用过程出现异常以及服务返回错误后被回调。

def on_close(self) -> None

服务关闭连接后被回调。

核心类(SpeechSynthesizer

SpeechSynthesizer可以通过“from dashscope.audio.tts import SpeechSynthesizer”方式引入。它的关键接口如下:

接口/方法

参数

返回值

描述

接口/方法

参数

返回值

描述

@classmethod
def call(cls,
         model: str,
         text: str,
         callback: ResultCallback = None,
         workspace: str = None,
         **kwargs) -> SpeechSynthesisResult:
  • model:模型名,参见模型列表

  • text:待合成文本

  • callback:回调类ResultCallback

  • workspace:DashScope workspace id,不必关注

  • kwargs:其它参数如format

合成结果SpeechSynthesisResult,同步调用时需要处理该返回,异步调用时不必处理

开启语音合成任务。根据是否传入参数callback,有如下两种情况:

  • 不传入callback参数:call函数将在语音合成完成后返回所有语音合成结果。

  • 传入callback参数:在语音合成过程中,服务器将回调callback中对应函数,流式返回语音合成结果。

call方法能够对请求参数进行设置。

错误码

在使用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)
  • 前提条件
  • 调用模式
  • 同步调用
  • 流式调用
  • 请求参数
  • 响应结果
  • 音频数据和时间戳信息(SpeechSynthesisResult)
  • 时间戳信息
  • 关键接口
  • 回调接口(ResultCallback)
  • 核心类(SpeechSynthesizer)
  • 错误码
  • 更多示例
  • 常见问题
  • 模型列表