全部产品
Search
文档中心

大模型服务平台百炼:Python SDK

更新时间:Oct 29, 2026

本文介绍 DashScope Python SDK 调用 Qwen-TTS-Realtime 系列模型时的关键接口与请求参数。

前期准备

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

快速开始

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

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

# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Receiving thread: iterate over the server events and write the audio to the file incrementally
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Create a real-time speech synthesis session: entering the with context automatically establishes the connection
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Notify the server that the input is complete (in server_commit mode the server decides when to synthesize)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

text_to_synthesize = [
    '这是第一句话。',
    '这是第二句话。',
    '这是第三句话。',
]

# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Receiving thread: iterate over the server events and write the audio to the file incrementally
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Create a real-time speech synthesis session: entering the with context automatically establishes the connection
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text in text_to_synthesize:
                print(f'send text: {text}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text})
                # In commit mode the client triggers the synthesis
                session.send_event({'type': 'input_text_buffer.commit'})
                time.sleep(0.1)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))

访问github下载更多示例代码。

请求参数

下述请求参数可以通过client.audio.realtime的connect方法设置。

参数

类型

是否必须

说明

model

str

是

模型名称。参见支持的模型。

ws_url

str

否

会话端点。缺省时由Client构造参数workspace/region自动推导(华北2(北京)地域:wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime;新加坡地域:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime)。

下述请求参数可以通过会话的update_session方法配置(具名参数直接传入,其余参数透传至session.update事件的session对象)。

参数

类型

是否必须

说明

voice

str

是

语音合成所使用的音色。参见Qwen-TTS音色列表。

language_type

str

否

指定合成音频的语种,默认为 Auto。

  • Auto:适用无法确定文本的语种或文本包含多种语言的场景,模型会自动为文本中的不同语言片段匹配各自的发音,但无法保证发音完全精准。

  • 指定语种:适用于文本为单一语种的场景,此时指定为具体语种,能显著提升合成质量,效果通常优于 Auto。可选值包括:

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

否

交互模式,可选值:

  • server_commit(默认):服务端自动判断合成时机,平衡延迟与质量,推荐大多数场景使用

  • commit:客户端手动触发合成,延迟最低,但需自行管理句子完整性

response_format

str

否

模型输出音频的格式。

支持的格式:

  • pcm(默认)

  • wav

  • mp3

  • opus

sample_rate

int

否

模型输出音频的采样率(Hz)。

支持的采样率:

  • 8000

  • 16000

  • 24000(默认)

  • 48000

speech_rate

float

否

音频的语速。1.0为正常语速,小于1.0为慢速,大于1.0为快速。

默认值:1.0。

取值范围:[0.5, 2.0]。

volume

int

否

音频的音量。

取值范围:[0, 100]。

pitch_rate

float

否

合成音频的语调。

默认值:1.0。

取值范围:[0.5, 2.0]。

bit_rate

int

否

指定音频的码率(kbps)。码率越大,音质越好,音频文件体积越大。仅在音频格式(response_format)为opus时可用。

默认值:128。

取值范围:[6, 510]。

关键接口

会话(RealtimeSession)

实时语音合成会话通过client.audio.realtime.connect(model=...)创建,进入with上下文时自动建立连接(也可调用会话的connect()方法手动建立)。

方法签名

服务端响应事件(通过events()迭代下发)

说明

def connect(self) -> "RealtimeSession"

session.created

会话已创建

session.updated

会话配置已更新

和服务端创建连接。进入with上下文时自动调用。

def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **kwargs) -> None

session.updated

会话配置已更新

更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。

在您建立链接,服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置,我们也推荐您总是在建立链接后即刻调用此接口。

服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。

def send_event(self,
               event: Dict[str, Any]) -> None

无

发送原始事件。文本输入通过input_text_buffer系列事件完成:将文本片段追加到云端输入文本缓冲区({"type": "input_text_buffer.append", "text": ...})。缓冲区是你可以写入并稍后提交的临时存储。

  • "server_commit"模式下,服务器决定何时提交并合成文本缓冲区中的文本。
  • "commit"模式下,客户端需要主动发送input_text_buffer.commit事件触发语音合成。
def send_event(self,
               event: Dict[str, Any]) -> None

input_text_buffer.cleared

清空服务端收到的文本

发送{"type": "input_text_buffer.clear"}事件,删除当前云端缓冲区的文本。

def send_event(self,
               event: Dict[str, Any]) -> None

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

响应完成

发送{"type": "input_text_buffer.commit"}事件,提交之前通过append添加到云端缓冲区的文本,并立刻合成所有文本。如果输入的文本缓冲区为空将产生错误。

  • "server_commit"模式下,客户端不需要发送此事件,服务器会自动提交文本缓冲区。
  • "commit"模式下,客户端必须通过commit触发语音合成。
def end_session(self) -> None

session.finished

响应完成

发送session.finish事件,终止任务。之后继续消费events()直到session.finished事件。

def close(self, ) -> None

无

关闭连接。退出with上下文时自动调用。

session.session_id

无

获取当前任务的session_id。

session.last_response_id

无

获取最近一次response的response_id。

session.last_first_audio_delay

无

获取首包音频延迟。

事件迭代(events())

服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。在接收线程中迭代会话的events()处理服务端事件,session.finished事件后迭代结束;error事件会以DashScopeError异常抛出,可使用try/except捕获。

方法

参数

返回值

描述

def events(self) -> Iterator[Dict]

event:服务端响应事件(dict)。

迭代器

包括对接口调用的回复响应和模型生成的文本和音频,session.finished事件后迭代结束。具体可以参考:服务端事件

def recv_event(self) -> Optional[Dict]

event:服务端响应事件(dict)。

事件或None

读取一条服务端事件,正常关闭后返回None。