Translate speech in real time using the DashScope Java SDK and the qwen3.5-livetranslate-flash-realtime model. The SDK connects over WebSocket, streams audio input, and returns translated text and synthesized speech.
Before you begin
- Install DashScope SDK version 2.22.5 or later.
- Get an API key.
- Set the API key as an environment variable:
- Review the Qwen-LiveTranslate model overview for supported languages and voices.
Quick start
Connect, send audio, and receive translated text:
Request parameters
OmniRealtimeParam
Build these with OmniRealtimeParam.builder() to establish the WebSocket connection.
Click to view the sample code
Click to view the sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | Model name. We recommend qwen3.5-livetranslate-flash-realtime. |
url | String | Yes | WebSocket endpoint. Use wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore) or wss://cn-beijing.maas.qwencloudapi.com/api-ws/v1/realtime (China North 2 (Beijing)). For other regions, replace ap-southeast-1 with the region ID. API keys are region-specific. See Regions. |
apikey | String | No | API key for authentication. If not set, configure it via the DASHSCOPE_API_KEY environment variable. |
OmniRealtimeConfig
Build these with OmniRealtimeConfig.builder() and then call conversation.updateSession(config) after connecting.
Click to view the sample code
Click to view the sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
modalities | List<OmniRealtimeModality> | No | Output modalities. Default: [AUDIO, TEXT]. Use [TEXT] for text-only output. |
voice | String | No | The voice for synthesized speech. The default voice for qwen3.5-livetranslate-flash-realtime is Tina. See supported voices. |
inputAudioFormat | OmniRealtimeAudioFormat | No | Input audio format. Default: PCM_16000HZ_MONO_16BIT. |
outputAudioFormat | OmniRealtimeAudioFormat | No | Output audio format. Default: PCM_24000HZ_MONO_16BIT. |
InputAudioTranscription | String | No | ASR model for transcribing original speech. Set to qwen3-asr-flash-realtime to receive source-language transcription alongside translation. |
translationConfig | OmniRealtimeTranslationParam | No | Translation settings. See OmniRealtimeTranslationParam below. |
enableTurnDetection | boolean | 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. |
OmniRealtimeConfig.builder().parameters(Map). The Map entries are written directly to session. For example, prepare these parameters to enable real-time voice cloning:
.voice("default") and add .parameters(parameters). Keep the existing language and audio settings, then call conversation.updateSession(config). See Voice cloning for the supported frequency and voice combinations.
OmniRealtimeTranslationParam
Build target language and custom terminology with OmniRealtimeTranslationParam.builder().
Click to view the sample code
Click to view the sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
language | String | No | Target language code. Default: en. See supported languages. |
corpus | Corpus | No | Custom terminology for domain-specific terms. |
corpus.phrases | Map<String, Object> | No | Term mapping: keys are source terms, values are target translations. Example: {"Inteligencia Artificial": "Artificial Intelligence"} |
Key interfaces
OmniRealtimeConversation
Manages the WebSocket connection and audio streaming lifecycle.
Import: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation
| Method | Description |
|---|---|
OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback) | Creates a conversation instance with connection parameters and an event callback. |
void connect() | Opens WebSocket connection. Triggers session.created and session.updated events. Throws NoApiKeyException, InterruptedException. |
void updateSession(OmniRealtimeConfig config) | Updates session configuration after connecting. Triggers session.updated event. Only set parameters you need; defaults apply for omitted parameters. |
void appendAudio(String audioBase64) | Sends Base64-encoded audio chunk to the server. The server automatically detects speech boundaries and triggers translation. |
void commit() | In Manual mode, commits audio previously appended to the server buffer via the appendAudio method. The server automatically begins generating a translation response upon receiving the commit. In VAD mode, this method does not need to be called as the server commits automatically. Triggers input_audio_buffer.committed event. |
void clearAppendedAudio() | Clears uncommitted audio data from the server buffer. Triggers input_audio_buffer.cleared event. |
void endSession() | Ends session gracefully. The server completes in-progress translation before sending session.finished. Throws InterruptedException. |
void close(int code, String reason) | Stops the task and closes WebSocket connection. |
String getSessionId() | Returns session ID. |
String getResponseId() | Returns response ID of the most recent server response. |
long getFirstTextDelay() | Returns first text delay of the most recent response (milliseconds). |
long getFirstAudioDelay() | Returns first audio delay of the most recent response (milliseconds). |
OmniRealtimeCallback
Handles server events delivered over WebSocket. Extend this class and implement each method to process events.
Import: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback
| Method | Parameters | Description |
|---|---|---|
void onOpen() | None | Called when WebSocket connection is established. |
abstract void onEvent(JsonObject message) | message: A JSON object containing a server-side event. | Called for each server event. Parse the type field to determine the event kind. |
abstract void onClose(int code, String reason) | code: WebSocket status code. reason: Closure description. | Called when WebSocket connection closes. |
onEvent:
| Event type | Description |
|---|---|
input_audio_buffer.speech_started | Server detected speech in audio stream. |
input_audio_buffer.speech_stopped | Server detected end of speech segment. |
conversation.item.input_audio_transcription.completed | Source-language transcription is ready. Read message.get("transcript"). Requires InputAudioTranscription to be set. |
response.audio_transcript.done | Translated text is ready. Read message.get("transcript"). |
response.audio.delta | A chunk of translated audio is available. Read message.get("delta") for Base64-encoded audio data. |
error | Error occurred. Read message.get("error").getAsJsonObject().get("message") for details. |
Complete example
This example captures microphone audio, translates it in real time, and plays translated speech through the system speaker.
What it does:
- Connects to Qwen-LiveTranslate over WebSocket.
- Configures Spanish-to-English translation with custom terminology.
- Streams microphone audio in 100 ms chunks.
- Prints original transcription and translated text.
- Plays translated audio through speaker.
Sample code for real-time microphone translation
Sample code for real-time microphone translation
| Placeholder | Description | Example |
|---|---|---|
<your-api-key> | QwenCloud API key | sk-xxxxxxxx |
Related topics
- Qwen-LiveTranslate model overview -- Supported languages, voices, and capabilities
- Server-side events reference -- Event types, JSON schemas, and error codes
- Install DashScope SDK -- Installation and dependency setup
- Get an API key -- Creation and management