This document describes how to use DashScope Python SDK to call the real-time audio and video translation (Qwen-LiveTranslate-Realtime) model.
See the current Qwen-LiveTranslate-Realtime Python SDK reference.
For connection and authentication, see WebSocket access. For event fields and JSON examples, see Client events and Server events.
Prerequisites
- Install the SDK. Make sure that your DashScope SDK version is 2.0.1 or later.
- 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.comtowss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
wss://dashscope-intl.aliyuncs.comtowss://{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.
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
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
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
# 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_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
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
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'}
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 signature | Server-side response event (delivered via events() iteration) | Description |
|---|---|---|
|
| Connect to the server. Automatically called when entering the |
| 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 |
|
| 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 |
|
| In Manual mode, submit the audio previously appended to the server buffer via the |
|
| Clear uncommitted audio data in the current server buffer. |
| None | Stop the task and close the connection. Automatically called when exiting the |
| None | Get the session ID (read from the |
| None | Get the response ID of the last response (read from the |
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 ( |
| event: Server-side event | Read one server event. Returns |
Complete example
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.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)
# 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()