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
- 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.
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
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'}
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 |
|---|---|---|
|
| 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 |