All Products
Search
Document Center

Alibaba Cloud Model Studio:Qwen-LiveTranslate-Realtime Python SDK

Last Updated:Nov 19, 2026

This document describes how to use DashScope Python SDK to call the real-time audio and video translation (Qwen-LiveTranslate-Realtime) model.

For connection and authentication, see WebSocket access. For event fields and JSON examples, see Client events and Server events.

Prerequisites

  1. Install the SDK. Make sure that your DashScope SDK version is 2.0.1 or later.
  2. Obtain an API key.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from wss://dashscope.aliyuncs.com to wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from wss://dashscope-intl.aliyuncs.com to wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Quick start

This example records microphone audio and translates it in real time.

Sample code for real-time translation from a microphone

import os
import sys
import base64
import signal
import pyaudio
from concurrent.futures import ThreadPoolExecutor

import dashscope
from dashscope import DashScopeError

def main():
    # Check for the API key.
    if not os.environ.get("DASHSCOPE_API_KEY"):
        print("Set the DASHSCOPE_API_KEY environment variable.")
        sys.exit(1)

    # 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.
    client = dashscope.Client(
        # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
        api_key=os.environ["DASHSCOPE_API_KEY"],
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    # Initialize PyAudio.
    pya = pyaudio.PyAudio()

    # Initialize the speaker for playing back the translated audio.
    speaker = pya.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=24000,
        output=True,
        frames_per_buffer=2400
    )

    # Initialize the microphone for capturing speech input.
    mic = pya.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=16000,
        input=True,
        frames_per_buffer=1600
    )

    # Create a real-time translation session: entering the with context automatically establishes the connection
    with client.audio.realtime.connect(
            model="qwen3.5-livetranslate-flash-realtime",
    ) as session:
        # Update the session configuration (recommended to call right after the connection is established)
        session.update_session(
            output_modalities=["text", "audio"],
            input_audio_transcription_model="qwen3-asr-flash-realtime",
            voice="Tina",
            translation_params={
                "language": "en",  # Target language for translation: English
                "corpus": {
                    "phrases": {
                        "Source Term 1": "Target Translation 1",
                        "Source Term 2": "Target Translation 2"
                    }
                }
            },
        )

        # Receiving thread: iterate over the server events
        def receive_events():
            try:
                for event in session.events():
                    event_type = event.get("type", "")
                    if event_type == "input_audio_buffer.speech_started":
                        print("====== Speech input detected ======")
                    elif event_type == "input_audio_buffer.speech_stopped":
                        print("====== Speech input ended ======")
                    elif event_type == "conversation.item.input_audio_transcription.completed":
                        print(f"[Original text] {event.get('transcript', '')}")
                    elif event_type == "response.audio_transcript.done":
                        print(f"[Translation result] {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"[Error] {e.message}")

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

            # Register the exit signal handler.
            def on_exit(sig, frame):
                print("\n[Exiting...]")
                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("[Starting real-time translation] Speak into the microphone. Press Ctrl+C to exit.")

            # Continuously capture and send microphone audio (append_audio also accepts raw bytes, encoded automatically)
            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()

Request parameters

  • Set the following parameters using the connect method of client.audio.realtime. Server events are no longer received via callbacks: iterate the session's events() in a receiving thread (see Event iteration (events())).

    Click to view sample code

    import os
    
    import dashscope
    
    # The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
    client = dashscope.Client(
        # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        workspace="{WorkspaceId}",
        region="cn-beijing",
    )
    
    # Create a real-time translation session: entering the with context automatically establishes the connection
    with client.audio.realtime.connect(
        model='qwen3.5-livetranslate-flash-realtime',
    ) as session:
        # Receiving thread: iterate over the server events
        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':
                # Process the incremental audio data (base64)
                audio_b64 = event.get('delta', '')
                # The audio data can be decoded and then played or saved
            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======')
    

    Parameter

    Type

    Required

    Description

    model

    str

    Yes

    The name of the model to use. Set this to qwen3.5-livetranslate-flash-realtime (recommended).

    ws_url

    str

    No

    The session endpoint. If omitted, the real-time translation service endpoint is automatically derived from the workspace/region constructor parameters of the Client (China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime; Singapore: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime).

    Replace {WorkspaceId} with your actual workspace ID.

  • Set the following parameters using the session's update_session method.

    Click to view sample code

    # Set the translation parameters
    translation_params = {
        'language': 'en',  # Target language
        'corpus': {
            'phrases': {
                'Inteligencia Artificial': 'Artificial Intelligence',
                'Aprendizaje Automático': 'Machine Learning'
            }
        }
    }
    
    # Update the session configuration
    session.update_session(
        output_modalities=['text', 'audio'],
        voice='Tina',
        translation_params=translation_params,
    )
    

    Parameter

    Type

    Required

    Description

    output_modalities

    List[str]

    No

    The output format for translation results.

    Default: ["text", "audio"].

    Valid values:

    • ["text"]: Outputs text only

    • ["text", "audio"]: Outputs text and audio

    voice

    str

    No

    The voice for audio output.

    Default:

    • Qwen3.5-LiveTranslate-Flash-Realtime: Tina

    Valid values: Supported voices.

    input_audio_transcription_model

    str

    No

    Set this parameter to qwen3-asr-flash-realtime to receive speech recognition results for the source language.

    translation_params

    Dict

    No

    Translation settings (target language and hotwords).

    enable_turn_detection

    bool

    No

    Whether to enable VAD (Voice Activity Detection).

    Default value: True, which enables VAD mode where the server automatically detects speech start/end and triggers translation.

    Set to False to switch to Manual mode, where the client manually submits audio via the commit method. For detailed parameter descriptions, see the turn_detection description in the Client events document.

  • Set the following parameters in the translation_params dictionary of the update_session method.

    Click to view sample code

    translation_params = {
        'language': 'en',  # Target language code
        'corpus': {
            'phrases': {
                'Inteligencia Artificial': 'Artificial Intelligence',  # Source phrase: Target translation
                'Aprendizaje Automático': 'Machine Learning'
            }
        }
    }
    

    Parameter

    Type

    Required

    Description

    language

    str

    No

    The target language for translation.

    Default: en.

    Valid values: Supported languages.

    corpus

    dict

    No

    A hotword mapping to improve translation accuracy for specific terms.

    corpus.phrases

    dict

    No

    The hotword mapping table where keys are source terms and values are target translations.

    Example: {'Inteligencia Artificial': 'Artificial Intelligence'}

API reference

Session (RealtimeSession)

The real-time translation session is created via client.audio.realtime.connect(model=...). The connection is automatically established when entering the with context (you can also call the session's connect() method to establish it manually).

Method signatureServer-side response event (delivered via events() iteration)Description
def connect(self) -> "RealtimeSession":

Server-side event

Session created

Server-side event

Session configuration updated

Connect to the server. Automatically called when entering the with context.

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:

Session updated

Session updated

Update session configuration. Call immediately after connecting. If you do not call this method, default configurations apply. Only the parameters of the session's update_session method apply.

def end_session(self) -> None

session.finished

The server completes the speech translation and ends the session

End the session. The server completes final translation processing.

def append_audio(self, audio_b64: Union[str, bytes]) -> None

None

Append audio chunks to the server-side input audio buffer. Accepts a Base64 string or raw bytes (automatically encoded). The server automatically detects speech start/end and triggers translation.

def commit(self) -> None

Server-side event

Input audio buffer committed

In Manual mode, submit the audio previously appended to the server buffer via the append_audio method. The server automatically starts generating translation responses upon receipt. In VAD mode, this method does not need to be called as the server commits automatically.

def clear_appended_audio(self) -> None:

Server-side event

Input audio buffer cleared

Clear uncommitted audio data in the current server buffer.

def close(self) -> None:

None

Stop the task and close the connection. Automatically called when exiting the with context.

session.session_id

None

Get the session ID (read from the session.created event).

session.last_response_id

None

Get the response ID of the last response (read from the response.created event).

Event iteration (events())

The server returns server-side response events and data to the client as events. Iterate the session's events() in a receiving thread to handle server events; iteration ends after the session.finished event.

error events are raised as DashScopeError exceptions, which you can catch with try/except in the receiving thread.

Continue receiving events after catching an error

When you catch DashScopeError, the current events() iterator has ended. Catching the exception in an outer try/except does not restart event reception.

If the WebSocket connection remains usable, correct the request and call events() again, or use recv_event() to read events one at a time. If the connection has closed, first reconnect and configure a new session, then resume receiving events.

To investigate the error, read the original server error event from the exception's body.

Method signatureParametersDescription
def events(self) -> Iterator[Dict[str, Any]]

event: Server-side event

Iterate over server events (dict). Iteration ends after the session.finished event. Consume from a single receiving thread; do not create multiple concurrent readers.

def recv_event(self) -> Optional[Dict[str, Any]]

event: Server-side event

Read one server event. Returns None after a normal close.