This document describes how to use DashScope Python SDK to call the real-time audio and video translation (Qwen-LiveTranslate-Realtime) model.
Prerequisites
- Install the SDK. Make sure that your DashScope SDK version is 2.0.1 or later.
- Obtain an API key.
Quick start
This example records microphone audio and translates it in real time.
Sample code for real-time translation from a microphone
Sample code for real-time translation from a microphone
Request parameters
-
Set the following parameters in the
connectmethod ofclient.audio.realtime. Server-side events are no longer received via callbacks: iterate the session'sevents()in a receiver thread (see Event iteration (events())).Click to view sample code
Parameter Type Required Description modelstrYes The name of the model to use. Set this to qwen3.5-livetranslate-flash-realtime(recommended).ws_urlstrNo The session endpoint. By default, the real-time translation service endpoint is automatically derived from the workspace/regionconstructor 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).Whenws_urlis specified, replace the domain with the API Host of your workspace, keeping the protocol and path unchanged. -
Set the following parameters using the
update_sessionmethod of the session.Click to view sample code
Parameter
Type
Required
Description
output_modalitiesList[str]No
The model output modalities.
Default:
["text", "audio"].Valid values:
["text"]: Outputs text only["text", "audio"]: Outputs text and audio
voicestrYes
The voice for audio output.
Default:
Qwen3.5-LiveTranslate-Flash-Realtime default voice:
Tina
Valid values: Supported voices.
input_audio_transcription_modelstrNo
Set this parameter to
qwen3-asr-flash-realtimeto receive speech recognition results for the source language.translation_paramsDictNo
Translation-related configuration.
enable_turn_detectionboolNo
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 the following parameters in the
translation_paramsdictionary of theupdate_sessionmethod.Click to view sample code
Parameter
Type
Required
Description
languagestrNo
The target language code for translation.
Default:
en.Valid values: Supported languages.
corpusdictNo
Hotword configuration, used to improve the translation accuracy of specific terms.
corpus.phrasesdictNo
The hotword mapping table where keys are source terms and values are target translations.
Example:
{'人工智能': 'Artificial Intelligence'}
API reference
Session (RealtimeSession)
Real-time translation sessions are created via client.audio.realtime.connect(model=...). Entering the with context establishes the connection automatically (you can also call the session's connect() method to connect manually).
| Method signature | Server-side response event (delivered via events() iteration) | Description |
|---|---|---|
Server-side eventSession createdServer-side event Session configuration updated | Connect to the server. Automatically called when entering the with context. | |
Server-side eventSession updated | Update session configuration. We recommend calling this method immediately after the connection is established. If you do not call this method, default configurations apply. You only need to focus on the parameters involved in the session's update_session method. | |
session.finishedThe server completes the speech translation and ends the session | Notify the server to end the session. Upon receiving the end-session notification, the server completes the final speech translation. | |
| None | Append audio data chunks to the cloud input audio buffer. Base64 strings and raw bytes (encoded automatically) are both supported. The server automatically detects the start and end of speech and triggers translation. | |
input_audio_buffer.committedInput 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. | |
input_audio_buffer.clearedInput audio buffer cleared | Clear uncommitted audio data in the current server buffer. | |
| None | Stop the task and close the connection. Automatically called when exiting the with context. | |
| None | Get the session ID of the current task (read from the session.created event). | |
| None | Get the response ID of the last response (read from the response.created event). |
Event iteration (events())
The server returns response events and data to the client as events. Iterate the session's events() in a receiver thread to process server-side events; iteration ends after the session.finished event.
The error event is raised as a DashScopeError exception, which you can catch with try/except in the receiver 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 signature | Parameters | Description |
|---|---|---|
| event: Server-side event | Iterate over server-side events (dict); iteration ends after the session.finished event. Consume events from a single receiver thread; do not create multiple concurrent readers. | |
| event: Server-side event | Read one server-side event; returns None after a normal close. |