跳转到主要内容
WebSocket

Qwen-LiveTranslate-Realtime Python SDK

本文档介绍如何使用 DashScope Python SDK 调用实时音视频翻译(Qwen-LiveTranslate-Realtime)模型。

前提条件

  1. 安装SDK,确保DashScope SDK版本不低于2.0.1。
  2. 获取与配置 API Key。

请求参数

  • 以下参数通过client.audio.realtime的connect方法设置。服务端事件不再通过回调接收:在接收线程中迭代会话的events()处理(见事件迭代(events()))。
import os

import dashscope

# 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 创建实时翻译会话:进入 with 上下文时自动建立连接
with client.audio.realtime.connect(
    model='qwen3.5-livetranslate-flash-realtime',
    ws_url='wss://maas.qianwenaiapi.com/api-ws/v1/realtime',
) as session:
    # 接收线程:迭代服务端事件
    for event in session.events():
        event_type = event.get('type', '')
        if event_type == 'session.created':
            print(f"Session created: {event['session']['id']}")
        elif event_type == 'response.audio_transcript.done':
            print(f"Translation result: {event['transcript']}")
        elif event_type == 'response.audio.delta':
            # 处理增量音频数据(base64)
            audio_b64 = event.get('delta', '')
            # 可将音频数据解码后播放或保存
        elif event_type == 'response.done':
            print('======Response Done======')
        elif event_type == 'input_audio_buffer.speech_started':
            print('======Speech Start======')
        elif event_type == 'input_audio_buffer.speech_stopped':
            print('======Speech Stop======')
参数类型是否必须说明
modelstr是指定要使用的模型名称,推荐使用qwen3.5-livetranslate-flash-realtime。
ws_urlstr否会话端点。不传时由 SDK 推导,服务端点为 wss://maas.qianwenaiapi.com/api-ws/v1/realtime。
  • 以下参数通过会话的update_session方法设置。
# 设置翻译参数
translation_params = {
    'language': 'en',  # 目标语言
    'corpus': {
        'phrases': {
            '人工智能': 'Artificial Intelligence',
            '机器学习': 'Machine Learning'
        }
    }
}

# 更新会话配置
session.update_session(
    output_modalities=['text', 'audio'],
    voice='Tina',
    translation_params=translation_params,
)
| 参数 | 类型 | 是否必须 | 说明 | |---|---|---|---|---| | output_modalities | List[str] | 否 | 模型输出模态。
默认值:["text", "audio"]。
取值范围:
  • ["text"]:仅输出文本
  • ["text", "audio"]:输出文本和音频
| | voice | str | 是 | 生成音频的音色。
默认值:Tina。可选值:参见支持的音色。 | | input_audio_transcription_model | str | 否 | 将input_audio_transcription_model设为qwen3-asr-flash-realtime,服务端将返回源语言语音识别结果。 | | translation_params | Dict | 否 | 翻译相关配置。 | | enable_turn_detection | bool | 否 | 是否启用 VAD(语音活动检测)。
默认值:True,即启用 VAD 模式,服务端自动检测语音起止并自动触发翻译。
设为False可切换为 Manual 模式,由客户端通过commit方法手动提交音频。详细参数说明参见turn_detection object (可选) 语音活动检测(VAD,Voice Activity Detection)配置,用于控制语音起止的检测方式: 设为配置对象(默认值):启用 VAD 模式。服务端自动检测语音起止,自动提交音频缓冲区并触发翻译响应,客户端无需发送input_audio_buffer.commit事件。 设为null:启用 Manual 模式。由客户端通过input_audio_buffer.commit事件手动提交音频缓冲区,服务端收到后自动开始生成翻译响应。 属性 type string (可选) VAD 类型,固定为server_vad。 threshold float (可选) VAD 检测灵敏度。值越低,越容易将微弱声音(包括背景噪音)识别为语音;值越高,需要更清晰、音量更大的语音才能触发。 取值范围:[-1.0, 1.0],默认值为 0.2。 silence_duration_ms integer (可选) 语音结束后需保持静音的最短时长(毫秒)。超过该时长后判定语音结束,服务端自动提交音频缓冲区并触发翻译响应。 取值范围:[200, 6000],默认值为 1000。。 |
  • 以下参数通过update_session方法的translation_params字典设置。
translation_params = {
    'language': 'en',  # 目标语言代码
    'corpus': {
        'phrases': {
            '人工智能': 'Artificial Intelligence',  # 源语言词: 目标语言翻译
            '机器学习': 'Machine Learning'
        }
    }
}
| 参数 | 类型 | 是否必须 | 说明 | |---|---|---|---|---| | language | str | 否 | 翻译目标语言代码。
默认值:en。
可选值:参见支持的语种。 | | corpus | dict | 否 | 热词配置,用于提升特定词汇的翻译准确性。 | | corpus.phrases | dict | 否 | 热词映射表。key 为源语言词汇,value 为目标语言对应翻译。
示例:{'人工智能': 'Artificial Intelligence'} |

关键接口

会话(RealtimeSession)

实时翻译会话通过client.audio.realtime.connect(model=...)创建,进入with上下文时自动建立连接(也可调用会话的connect()方法手动建立)。
方法签名服务端响应事件(通过events()迭代下发)说明
示例 1 请参见表格下方服务端事件 > 会话已创建 服务端事件 > 会话配置已更新和服务端创建连接。进入with上下文时自动调用。
示例 2 请参见表格下方服务端事件 > 会话已更新用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注会话update_session方法涉及的参数。
示例 3 请参见表格下方session.finished > 服务端完成语音翻译,结束会话通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音翻译。
示例 4 请参见表格下方无将音频数据片段追加到云端输入音频缓冲区,支持Base64字符串或原始bytes(自动编码)。服务端会自动检测语音起止并触发翻译。
示例 5 请参见表格下方input_audio_buffer.committed > 输入音频缓冲区已提交Manual 模式下,提交之前通过append_audio方法追加到云端缓冲区的音频,服务端收到后自动开始生成翻译响应。VAD 模式下无需调用此方法,服务端会自动提交。
示例 6 请参见表格下方input_audio_buffer.cleared > 输入音频缓冲区已清空清空当前云端缓冲区中尚未提交的音频数据。
示例 7 请参见表格下方无终止任务,并关闭连接。退出with上下文时自动调用。
示例 8 请参见表格下方无获取当前任务的session_id(从session.created事件读取)。
示例 9 请参见表格下方无获取最近一次response的response_id(从response.created事件读取)。
示例 1(方法签名):
def connect(self) -> "RealtimeSession"
示例 2(方法签名):
def update_session(self,
    output_modalities: List[str],
    *,
    voice: str = None,
    input_audio_transcription_model: str = None,
    translation_params: Dict[str, Any] = None,
    enable_turn_detection: bool = None,
    **kwargs) -> None:
示例 3(方法签名):
def end_session(self) -> None
示例 4(方法签名):
def append_audio(self, audio_b64: Union[str, bytes]) -> None
示例 5(方法签名):
def commit(self) -> None
示例 6(方法签名):
def clear_appended_audio(self) -> None
示例 7(方法签名):
def close(self) -> None
示例 8(方法签名):
session.session_id
示例 9(方法签名):
session.last_response_id

事件迭代(events())

服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。在接收线程中迭代会话的events()处理服务端事件,session.finished事件后迭代结束。 error事件会以DashScopeError异常抛出,可在接收线程中使用try/except捕获。 捕获异常后如何继续接收事件 捕获 DashScopeError 后,原来的 events() 迭代已经结束。仅在外层使用 try/except 捕获异常,不会让它自动继续接收事件。 如果 WebSocket 连接仍可用,修正请求后重新调用 events(),或用 recv_event() 逐条接收。连接已关闭时,先重新建连并配置会话,再开始接收。 排查错误原因时,可从异常的 body 读取服务端返回的原始错误事件。
方法签名参数说明
示例 1 请参见表格下方event:服务端事件迭代接收服务端事件(dict),session.finished事件后迭代结束。请由一个接收线程持续消费,不要并发创建多个读取者。
示例 2 请参见表格下方event:服务端事件读取一条服务端事件,正常关闭后返回None。
示例 1(方法签名):
def events(self) -> Iterator[Dict[str, Any]]
示例 2(方法签名):
def recv_event(self) -> Optional[Dict[str, Any]]

完整示例

以下示例展示如何从麦克风实时录音并进行翻译。
import os
import sys
import base64
import signal
import pyaudio
from concurrent.futures import ThreadPoolExecutor

import dashscope
from dashscope import DashScopeError

def main():
    # 检查 API Key
    if not os.environ.get("DASHSCOPE_API_KEY"):
        print("请设置环境变量 DASHSCOPE_API_KEY")
        sys.exit(1)

    # 以下为千问AI平台的接口配置
    client = dashscope.Client(
        # 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
        api_key=os.environ["DASHSCOPE_API_KEY"],
    )

    # 初始化 PyAudio
    pya = pyaudio.PyAudio()

    # 初始化扬声器(用于播放翻译后的语音)
    speaker = pya.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=24000,
        output=True,
        frames_per_buffer=2400
    )

    # 初始化麦克风(用于采集语音输入)
    mic = pya.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=16000,
        input=True,
        frames_per_buffer=1600
    )

    # 创建实时翻译会话:进入 with 上下文时自动建立连接
    with client.audio.realtime.connect(
            model="qwen3.5-livetranslate-flash-realtime",
            ws_url="wss://maas.qianwenaiapi.com/api-ws/v1/realtime",
    ) as session:
        # 更新会话配置(建议连接建立后首先调用)
        session.update_session(
            output_modalities=["text", "audio"],
            input_audio_transcription_model="qwen3-asr-flash-realtime",
            voice="Tina",
            translation_params={
                "language": "en",  # 翻译目标语言:英语
                "corpus": {
                    "phrases": {
                        "人工智能": "Artificial Intelligence",
                        "机器学习": "Machine Learning"
                    }
                }
            },
        )

        # 接收线程:迭代服务端事件
        def receive_events():
            try:
                for event in session.events():
                    event_type = event.get("type", "")
                    if event_type == "input_audio_buffer.speech_started":
                        print("====== 检测到语音输入 ======")
                    elif event_type == "input_audio_buffer.speech_stopped":
                        print("====== 语音输入结束 ======")
                    elif event_type == "conversation.item.input_audio_transcription.completed":
                        print(f"[原文] {event.get('transcript', '')}")
                    elif event_type == "response.audio_transcript.done":
                        print(f"[翻译结果] {event.get('transcript', '')}")
                    elif event_type == "response.audio.delta":
                        audio_b64 = event.get("delta", "")
                        if audio_b64:
                            speaker.write(base64.b64decode(audio_b64))
            except DashScopeError as e:
                print(f"[错误] {e.message}")

        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events)

            # 注册退出信号处理
            def on_exit(sig, frame):
                print("\n[正在退出...]")
                session.end_session()
                session.close()
                mic.stop_stream()
                mic.close()
                speaker.stop_stream()
                speaker.close()
                pya.terminate()
                sys.exit(0)

            signal.signal(signal.SIGINT, on_exit)

            print("[开始实时翻译] 请对着麦克风说话,按 Ctrl+C 退出")

            # 持续采集麦克风音频并发送(append_audio 也接受原始 bytes,自动编码)
            try:
                while True:
                    audio_data = mic.read(1600, exception_on_overflow=False)
                    session.append_audio(audio_data)
            finally:
                session.end_session()
                receiver.result()

if __name__ == "__main__":
    main()