Skip to main content
WebSocket

Qwen-LiveTranslate Python SDK - API reference

Use the DashScope SDK for Python to call Qwen-LiveTranslate for real-time speech translation.

Prerequisites

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

Request parameters

client.audio.realtime.connect

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())).
import os

import dashscope

# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# 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',
    # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
    # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
    ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/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. Pass wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore). For another region, replace ap-southeast-1 in the URL. See Regions and endpoints.

Session configuration

Set the following parameters using the session's update_session method.
# 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.

translation_params

Set the following parameters in the translation_params dictionary of the update_session method.
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'}

Key interfaces

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
NoneAppend 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:
NoneStop the task and close the connection. Automatically called when exiting the with context.
session.session_id
NoneGet the session ID (read from the session.created event).
session.last_response_id
NoneGet 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 eventIterate 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 eventRead one server event. Returns None after a normal close.

Complete example

This example records microphone audio and translates it in real time.
import os
import sys
import base64
import signal
import pyaudio
from concurrent.futures import ThreadPoolExecutor

import dashscope
from dashscope.v2 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)

    # If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
    client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

    # 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",
            # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
            # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
            ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/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()