实时语音合成 Python SDK
DashScope Python SDK 调用实时语音合成（Qwen）的接口和参数说明。
指南：模型详情请参见实时语音合成 - Qwen 或语音合成 - Qwen。
支持两种交互模式：server commit（服务端决定合成时机）和 commit（客户端手动触发合成）。完整示例和教程请参见实时语音合成。
在
通过
通过
通过实现回调方法处理服务端响应。
通过
快速开始
支持两种交互模式：server commit（服务端决定合成时机）和 commit（客户端手动触发合成）。完整示例和教程请参见实时语音合成。
请求参数
在 QwenTtsRealtime 构造函数中设置以下参数。
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| model | str | 是 | 模型名称。 |
| url | str | 否 | WebSocket 端点地址。默认值：wss://dashscope.aliyuncs.com/api-ws/v1/realtime。不传时 SDK 自动使用默认端点。 |
update_session 设置以下参数。
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| voice | str | 是 | 合成音色。音色名称区分大小写，请使用正确大小写（例如 Cherry，而非 cherry）。系统音色：适用于 Qwen3-TTS-Instruct-Flash-Realtime、Qwen3-TTS-Flash-Realtime 和 Qwen-TTS-Realtime 系列。自定义音色：通过声音复刻（Qwen）创建（仅限 Qwen3-TTS-VC-Realtime 系列）或声音设计（Qwen）创建（仅限 Qwen3-TTS-VD-Realtime 系列）。 |
| language_type | str | 否 | 输出音频的语言。默认值：Auto。语言不确定或文本混合多种语言时使用 Auto。支持：Chinese、English、German、Italian、Portuguese、Spanish、Japanese、Korean、French、Russian。指定语言可提升合成质量。 |
| mode | str | 否 | 交互模式。server_commit（默认）：服务端决定合成时机，平衡延迟和质量，适合大多数场景。commit：客户端手动触发合成，延迟更低，但需要自行管理句子边界。 |
| format | str | 否 | 音频格式。支持：pcm（默认）、wav、mp3、opus。Qwen-TTS-Realtime 仅支持 pcm。 |
| sample_rate | int | 否 | 采样率，单位 Hz。支持：8000、16000、24000（默认）、48000。Qwen-TTS-Realtime 仅支持 24000。 |
| speech_rate | float | 否 | 语速倍数。默认值：1.0（正常语速）。范围：[0.5, 2.0]。Qwen-TTS-Realtime 不支持。 |
| volume | int | 否 | 音量。默认值：50。范围：[0, 100]。Qwen-TTS-Realtime 不支持。 |
| pitch_rate | float | 否 | 音高倍数。默认值：1.0。范围：[0.5, 2.0]。Qwen-TTS-Realtime 不支持。 |
| bit_rate | int | 否 | 比特率，单位 kbps。值越高音质越好，但文件更大。仅用于 opus 格式。默认值：128。范围：[6, 510]。Qwen-TTS-Realtime 不支持。 |
| instructions | str | 否 | 合成控制指令。详情请参见实时流式语音合成。默认值：None。最大长度：1600 tokens。支持中英文。仅限 Qwen3-TTS-Instruct-Flash-Realtime 系列。 |
| optimize_instructions | bool | 否 | 设为 True 时，对 instructions 进行改写以提升自然度和表现力。默认值：False。适用于精细化语音控制场景。需先设置 instructions。仅限 Qwen3-TTS-Instruct-Flash-Realtime 系列。 |
核心接口
QwenTtsRealtime 类
通过 from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime 导入。
| 方法签名 | 服务端响应事件（通过回调返回） | 说明 |
|---|---|---|
def connect(self) -> None | session.created - 会话已创建。session.updated - 会话配置已更新。 | 连接服务端。 |
def update_session(self, voice: str, response_format: AudioFormat = AudioFormat.PCM_24000HZ_MONO_16BIT, mode: str = 'server_commit', language_type: str = None, **kwargs) -> None | session.updated - 会话配置已更新。 | 更新会话配置。参数详情请参见"请求参数"。连接后立即调用以覆盖默认值。无效参数返回错误，有效参数更新配置。 |
def append_text(self, text: str) -> None | 无 | 向云端输入缓冲区追加文本。server_commit 模式下，服务端决定何时合成缓冲区中的文本。commit 模式下，调用 commit 触发合成。 |
def clear_appended_text(self) -> None | input_text_buffer.cleared - 缓冲区已清空。 | 清空云端缓冲区中的所有文本。 |
def commit(self) -> None | input_text_buffer.committed - 文本已提交。response.output_item.added - 输出项已添加。response.content_part.added - 内容片段已添加。response.audio.delta - 增量音频数据。response.audio.done - 音频生成完成。response.content_part.done - 内容流式传输完成。response.output_item.done - 输出项完成。response.done - 响应完成。 | 提交缓冲区文本并立即合成。缓冲区为空时返回错误。server_commit 模式下无需调用。commit 模式下必须调用以触发合成。 |
def finish(self) -> None | session.finished - 会话已结束。 | 结束任务。 |
def close(self) -> None | 无 | 关闭连接。 |
def get_session_id(self) -> str | 无 | 获取当前会话 ID。 |
def get_last_response_id(self) -> str | 无 | 获取最近一次响应 ID。 |
def get_first_audio_delay(self) | 无 | 获取首个音频包的延迟时间。 |
回调接口（QwenTtsRealtimeCallback）
通过实现回调方法处理服务端响应。
通过 from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback 导入。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
def on_open(self) -> None | 无 | 无 | 连接建立时调用。 |
def on_event(self, message: str) -> None | message：服务端响应事件。 | 无 | 收到 API 响应和模型生成的文本/音频时调用。详情请参见服务端事件。 |
def on_close(self, close_status_code, close_msg) -> None | close_status_code：WebSocket 关闭状态码。close_msg：WebSocket 关闭消息。 | 无 | 服务端关闭连接时调用。 |
