跳转到主要内容
Qwen3-TTS-Realtime

Python SDK

本文介绍通过 DashScope Python SDK 进行实时语音合成的关键接口、请求参数和示例代码。

本文介绍 DashScope Python SDK 调用实时语音合成时的关键接口与请求参数。 用户指南:关于模型介绍和选型建议请参见实时语音合成或非实时语音合成。

前期准备

DashScope Python SDK 版本需要不低于1.25.11。

快速开始

import os
import base64
import threading
import time
import dashscope
from dashscope.audio.qwen_tts_realtime import *

qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    '对吧~我就特别喜欢这种超市,',
    '尤其是过年的时候',
    '去逛超市',
    '就会觉得',
    '超级超级开心!',
    '想买好多好多的东西呢!'
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        Set your DashScope API-key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # load API-key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # set API-key manually

class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        self.complete_event = threading.Event()
        self.file = open('result_24k.pcm', 'wb')

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        self.file.close()
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_finished(self):
        self.complete_event.wait()

if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        model='qwen3-tts-flash-realtime',
        callback=callback,
        url='wss://maas.qianwenaiapi.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        mode = 'server_commit'
    )
    for text_chunk in text_to_synthesize:
        print(f'send text: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)
    qwen_tts_realtime.finish()
    callback.wait_for_finished()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(),
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))
访问github下载更多示例代码。

请求参数

下述请求参数可以通过QwenTtsRealtime的构造方法进行设置。
参数类型是否必须说明
modelstr是模型名称。参见支持的模型。
urlstr是wss://maas.qianwenaiapi.com/api-ws/v1/realtime
下述请求参数可以通过update_session接口配置。
参数类型是否必须说明
voicestr是语音合成所使用的音色。参见支持的音色。
支持系统音色:
  • 系统音色:仅限千问3-TTS-Flash-Realtime和千问-TTS-Realtime系列模型。音色效果请参见:支持的音色。
language_typestr否指定合成音频的语种,默认为 Auto。
  • Auto:适用无法确定文本的语种或文本包含多种语言的场景,模型会自动为文本中的不同语言片段匹配各自的发音,但无法保证发音完全精准。
  • 指定语种:适用于文本为单一语种的场景,此时指定为具体语种,能显著提升合成质量,效果通常优于 Auto。可选值包括:
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian
modestr否交互模式,可选值:
  • server_commit(默认):服务端自动判断合成时机,平衡延迟与质量,推荐大多数场景使用
  • commit:客户端手动触发合成,延迟最低,但需自行管理句子完整性
formatstr否模型输出音频的格式。
支持的格式:
  • pcm(默认)
  • wav
  • mp3
  • opus
千问-TTS-Realtime(参见支持的模型)仅支持pcm。
sample_rateint否模型输出音频的采样率(Hz)。
支持的采样率:
  • 8000
  • 16000
  • 24000(默认)
  • 48000
千问-TTS-Realtime(参见支持的模型)仅支持24000。
speech_ratefloat否音频的语速。1.0为正常语速,小于1.0为慢速,大于1.0为快速。
默认值:1.0。
取值范围:[0.5, 2.0]。
千问-TTS-Realtime(参见支持的模型)不支持该参数。
volumeint否音频的音量。
默认值:50。
取值范围:[0, 100]。
千问-TTS-Realtime(参见支持的模型)不支持该参数。
pitch_ratefloat否合成音频的语调。
默认值:1.0。
取值范围:[0.5, 2.0]。
千问-TTS-Realtime(参见支持的模型)不支持该参数。
bit_rateint否指定音频的码率(kbps)。码率越大,音质越好,音频文件体积越大。仅在音频格式(response_format)为opus时可用。
默认值:128。
取值范围:[6, 510]。
千问-TTS-Realtime(参见支持的模型)不支持该参数。
instructionsstr否设置指令,参见指令控制。
默认值:无默认值,不设置不生效。
长度限制:长度不得超过 1600 Token。
支持语言:仅支持中文和英文。
指令控制功能已迁移至CosyVoice系列模型,详见指令控制。
optimize_instructionsbool否是否对 instructions 进行优化,以提升语音合成的自然度和表现力。
默认值:False
行为说明:当设置为 True 时,系统将对 instructions 的内容进行语义增强与重写,生成更适合语音合成的内部指令。
适用场景:推荐在追求高品质、精细化语音表达的场景下开启。
依赖关系:此参数依赖于 instructions 参数被设置。如果 instructions 为空,此参数不生效。
指令控制功能已迁移至CosyVoice系列模型,详见指令控制。

关键接口

QwenTtsRealtime类

QwenTtsRealtime通过from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime方法引入。
方法签名服务端响应事件(通过回调下发)说明
示例 1 请参见表格下方session.created > 会话已创建 session.updated > 会话配置已更新和服务端创建连接。
示例 2 请参见表格下方session.updated > 会话配置已更新更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。 在您建立链接,服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置,我们也推荐您总是在建立链接后即刻调用此接口。 服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。
示例 3 请参见表格下方无将文本片段追加到云端输入文本缓冲区。 缓冲区是你可以写入并稍后提交的临时存储。
  • "server_commit"模式下,服务器决定何时提交并合成文本缓冲区中的文本。
  • "commit"模式下,客户端需要主动通过commit触发语音合成。
示例 4 请参见表格下方input_text_buffer.cleared > 清空服务端收到的文本删除当前云端缓冲区的文本。
示例 5 请参见表格下方input_text_buffer.committed > 提交文本并触发语音合成 response.output_item.added > 响应时有新的输出内容 response.content_part.added > 新的输出内容添加到assistant message 项 response.audio.delta > 模型增量生成的音频 response.audio.done > 完成音频生成 response.content_part.done > Assistant message 的音频内容流式输出完成 response.output_item.done > Assistant message 的整个输出项流式传输完成 response.done > 响应完成提交之前通过append添加到云端缓冲区的文本,并立刻合成所有文本。如果输入的文本缓冲区为空将产生错误。
  • "server_commit"模式下,客户端不需要发送此事件,服务器会自动提交文本缓冲区。
  • "commit"模式下,客户端必须通过commit触发语音合成。
示例 6 请参见表格下方session.finished > 响应完成终止任务。
示例 7 请参见表格下方无关闭连接。
示例 8 请参见表格下方无获取当前任务的session_id。
示例 9 请参见表格下方无获取最近一次response的response_id。
示例 10 请参见表格下方无获取首包音频延迟。
示例 1(方法签名):
def connect(self) -> None
示例 2(方法签名):
def update_session(self,
                   voice: str,
                   response_format: AudioFormat = AudioFormat.
                   PCM_24000HZ_MONO_16BIT,
                   mode: str = 'server_commit',
                   language_type : str = "Chinese",
                   **kwargs) -> None
示例 3(方法签名):
def append_text(self, text: str) -> None
示例 4(方法签名):
def clear_appended_text(self, ) -> None
示例 5(方法签名):
def commit(self, ) -> None
示例 6(方法签名):
def finish(self, ) -> None
示例 7(方法签名):
def close(self, ) -> None
示例 8(方法签名):
def get_session_id(self) -> str
示例 9(方法签名):
def get_last_response_id(self) -> str
示例 10(方法签名):
def get_first_audio_delay(self)

回调接口(QwenTtsRealtimeCallback)

服务端会通过回调的方式,将服务端响应事件和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。 通过from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback引入。
方法参数返回值描述
示例 1 请参见表格下方无无当和服务端建立连接完成后,该方法立刻被回调。
示例 2 请参见表格下方message:服务端响应事件。无包括对接口调用的回复响应和模型生成的文本和音频。具体可以参考:服务端事件
示例 3 请参见表格下方close_status_code:关闭WebSocket的状态码。 close_msg:关闭WebSocket的关闭信息。无当服务已经关闭连接后进行回调。
示例 1(方法):
def on_open(self) -> None
示例 2(方法):
def on_event(self, message: str) -> None
示例 3(方法):
def on_close(self, close_status_code, close_msg) -> None