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 using the
connectmethod ofclient.audio.realtime. Server events are no longer received via callbacks: iterate the session'sevents()in a receiving 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. If omitted, 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).Replace
{WorkspaceId}with your actual workspace ID. -
Set the following parameters using the session's
update_sessionmethod.Click to view sample code
Parameter
Type
Required
Description
output_modalitiesList[str]No
The output format for translation results.
Default:
["text", "audio"].Valid values:
["text"]: Outputs text only["text", "audio"]: Outputs text and audio
voicestrNo
The voice for audio output.
Default:
Qwen3.5-LiveTranslate-Flash-Realtime:
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 settings (target language and hotwords).
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 to
Falseto switch to Manual mode, where the client manually submits audio via thecommitmethod. For detailed parameter descriptions, see theturn_detectiondescription in the Client events document. -
Set the following parameters in the
translation_paramsdictionary of theupdate_sessionmethod.Click to view sample code
Parameter
Type
Required
Description
languagestrNo
The target language for translation.
Default:
en.Valid values: Supported languages.
corpusdictNo
A hotword mapping to improve translation accuracy for specific terms.
corpus.phrasesdictNo
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 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. | |
Session updatedSession 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. | |
session.finishedThe server completes the speech translation and ends the session | End the session. The server completes final translation processing. | |
| 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. | |
Server-side eventInput 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. | |
Server-side eventInput 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 (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 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 signature | Parameters | Description |
|---|---|---|
| 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. | |
| event: Server-side event | Read one server event. Returns None after a normal close. |