Skip to main content
WebSocket

Qwen-LiveTranslate Java SDK - API reference

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

  1. Install DashScope SDK version 2.22.5 or later.
  2. Get an API key.
  3. Set the API key as an environment variable:
   # Linux / macOS
   export DASHSCOPE_API_KEY=<your-api-key>
   source ~/.bashrc

   # Windows
   set DASHSCOPE_API_KEY=<your-api-key>
  1. Review the Qwen-LiveTranslate model overview for supported languages and voices.

Quick start

Connect, send audio, and receive translated text:
import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import java.util.Arrays;

// 1. Build connection parameters
OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3.5-livetranslate-flash-realtime")
        // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        .url("wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime")
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();

// 2. Define a callback to handle server events
OmniRealtimeCallback callback = new OmniRealtimeCallback() {
    @Override public void onOpen() { System.out.println("Connected"); }

    @Override
    public void onEvent(JsonObject message) {
        String type = message.get("type").getAsString();
        if ("response.audio_transcript.done".equals(type)) {
            System.out.println("Translation: " + message.get("transcript").getAsString());
        }
    }

    @Override
    public void onClose(int code, String reason) {
        System.out.println("Closed: " + code + " " + reason);
    }
};

// 3. Open a session and start streaming audio
OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);
conversation.connect();

// 4. Configure translation target language
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .translationConfig(OmniRealtimeTranslationParam.builder()
                .language("en")
                .build())
        .build();
conversation.updateSession(config);

// 5. Send Base64-encoded audio chunks (PCM 16 kHz, 16-bit, mono)
conversation.appendAudio(audioBase64);

// 6. End the session when done
conversation.endSession();

Request parameters

OmniRealtimeParam

Build these with OmniRealtimeParam.builder() to establish the WebSocket connection.
OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3.5-livetranslate-flash-realtime")
        // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        .url("wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime")
        // API keys vary by region. To obtain an API key, see /api-reference/preparation/api-key
        // If an environment variable is not configured, replace the next line with your QwenCloud API key: .apikey("sk-xxx")
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();
ParameterTypeRequiredDescription
modelStringYesModel name. We recommend qwen3.5-livetranslate-flash-realtime.
urlStringYesWebSocket 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.
apikeyStringNoAPI 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.
// Set custom translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Cherry")
        .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
        .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
        .InputAudioTranscription("qwen3-asr-flash-realtime")
        .translationConfig(OmniRealtimeTranslationParam.builder()
                .language("en")
                .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                        .phrases(phrases)
                        .build())
                .build())
        .build();

conversation.updateSession(config);
ParameterTypeRequiredDescription
modalitiesList<OmniRealtimeModality>NoOutput modalities. Default: [AUDIO, TEXT]. Use [TEXT] for text-only output.
voiceStringNoThe voice for synthesized speech. The default voice for qwen3.5-livetranslate-flash-realtime is Tina. See supported voices.
inputAudioFormatOmniRealtimeAudioFormatNoInput audio format. Default: PCM_16000HZ_MONO_16BIT.
outputAudioFormatOmniRealtimeAudioFormatNoOutput audio format. Default: PCM_24000HZ_MONO_16BIT.
InputAudioTranscriptionStringNoASR model for transcribing original speech. Set to qwen3-asr-flash-realtime to receive source-language transcription alongside translation.
translationConfigOmniRealtimeTranslationParamNoTranslation settings. See OmniRealtimeTranslationParam below.
enableTurnDetectionbooleanNoWhether 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.
Extra session parameters Some session parameters have no dedicated SDK configuration method. Pass them through OmniRealtimeConfig.builder().parameters(Map). The Map entries are written directly to session. For example, prepare these parameters to enable real-time voice cloning:
Map<String, Object> options = new HashMap<>();
options.put("frequency", "once");

Map<String, Object> parameters = new HashMap<>();
parameters.put("enable_voice_clone", true);
parameters.put("voice_clone_options", options);
In the existing configuration builder chain, set .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().
// Set translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");  // Source language word: Target language translation
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder()
        .language("en")  // Target language code
        .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                .phrases(phrases)
                .build())
        .build();
ParameterTypeRequiredDescription
languageStringNoTarget language code. Default: en. See supported languages.
corpusCorpusNoCustom terminology for domain-specific terms.
corpus.phrasesMap<String, Object>NoTerm 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
MethodDescription
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
MethodParametersDescription
void onOpen()NoneCalled 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.
Common event types received in onEvent:
Event typeDescription
input_audio_buffer.speech_startedServer detected speech in audio stream.
input_audio_buffer.speech_stoppedServer detected end of speech segment.
conversation.item.input_audio_transcription.completedSource-language transcription is ready. Read message.get("transcript"). Requires InputAudioTranscription to be set.
response.audio_transcript.doneTranslated text is ready. Read message.get("transcript").
response.audio.deltaA chunk of translated audio is available. Read message.get("delta") for Base64-encoded audio data.
errorError 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:
  1. Connects to Qwen-LiveTranslate over WebSocket.
  2. Configures Spanish-to-English translation with custom terminology.
  3. Streams microphone audio in 100 ms chunks.
  4. Prints original transcription and translated text.
  5. Plays translated audio through speaker.
import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;

import javax.sound.sampled.*;
import java.util.*;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * Example of using a microphone with the real-time audio and video translation model.
 */
public class Main {
    private static final int INPUT_CHUNK_SIZE = 3200;   // 100 ms of 16 kHz, 16-bit, mono audio
    private static final int OUTPUT_CHUNK_SIZE = 4800;  // 100 ms of 24 kHz, 16-bit, mono audio
    private static final AtomicBoolean running = new AtomicBoolean(true);
    private static SourceDataLine speaker;  // Speaker

    public static void main(String[] args) throws InterruptedException {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("Set the DASHSCOPE_API_KEY environment variable.");
            System.exit(1);
        }

        // Create connection parameters.
        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3.5-livetranslate-flash-realtime")
                // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
                // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
                .url("wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime")
                .apikey(apiKey)
                .build();

        // Create a callback handler.
        OmniRealtimeCallback callback = new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("[Connection established]");
            }

            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch (type) {
                    case "input_audio_buffer.speech_started":
                        System.out.println("====== Speech input detected ======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("====== Speech input ended ======");
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        String originalText = message.get("transcript").getAsString();
                        System.out.println("[Original text] " + originalText);
                        break;
                    case "response.audio_transcript.done":
                        String translatedText = message.get("transcript").getAsString();
                        System.out.println("[Translation result] " + translatedText);
                        break;
                    case "response.audio.delta":
                        // Decode and play the translated audio.
                        String audioB64 = message.get("delta").getAsString();
                        byte[] audioBytes = Base64.getDecoder().decode(audioB64);
                        if (speaker != null) {
                            speaker.write(audioBytes, 0, audioBytes.length);
                        }
                        break;
                    case "error":
                        JsonObject error = message.get("error").getAsJsonObject();
                        System.err.println("[Error] " + error.get("message").getAsString());
                        break;
                }
            }

            @Override
            public void onClose(int code, String reason) {
                System.out.println("[Connection closed] code: " + code + ", reason: " + reason);
            }
        };

        // Create a session.
        OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);

        try {
            // Initialize the speaker (for playing the translated speech).
            AudioFormat speakerFormat = new AudioFormat(24000, 16, 1, true, false);
            DataLine.Info speakerInfo = new DataLine.Info(SourceDataLine.class, speakerFormat);
            speaker = (SourceDataLine) AudioSystem.getLine(speakerInfo);
            speaker.open(speakerFormat, OUTPUT_CHUNK_SIZE * 4);
            speaker.start();

            // Initialize the microphone (for capturing speech input).
            AudioFormat micFormat = new AudioFormat(16000, 16, 1, true, false);
            DataLine.Info micInfo = new DataLine.Info(TargetDataLine.class, micFormat);
            if (!AudioSystem.isLineSupported(micInfo)) {
                System.err.println("Microphone is not available.");
                System.exit(1);
            }
            TargetDataLine microphone = (TargetDataLine) AudioSystem.getLine(micInfo);
            microphone.open(micFormat);
            microphone.start();

            // Connect to the server.
            conversation.connect();

            // Configure translation parameters.
            Map<String, Object> phrases = new HashMap<>();
            phrases.put("Inteligencia Artificial", "Artificial Intelligence");
            phrases.put("Aprendizaje Automático", "Machine Learning");

            OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                    .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
                    .voice("Cherry")
                    .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
                    .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
                    .InputAudioTranscription("qwen3-asr-flash-realtime")
                    .translationConfig(OmniRealtimeTranslationParam.builder()
                            .language("en")
                            .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                                    .phrases(phrases)
                                    .build())
                            .build())
                    .build();

            conversation.updateSession(config);

            // Register a shutdown hook.
            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
                System.out.println("\n[Exiting...]");
                running.set(false);
                microphone.stop();
                microphone.close();
                speaker.stop();
                speaker.close();
                try {
                    conversation.endSession();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
                conversation.close(1000, "User stopped");
            }));

            System.out.println("[Starting real-time translation] Speak into the microphone. Press Ctrl+C to exit.");

            // Continuously capture and send microphone audio.
            byte[] buffer = new byte[INPUT_CHUNK_SIZE];
            while (running.get()) {
                int bytesRead = microphone.read(buffer, 0, buffer.length);
                if (bytesRead > 0) {
                    conversation.appendAudio(Base64.getEncoder().encodeToString(buffer));
                }
            }

        } catch (NoApiKeyException e) {
            System.err.println("API Key error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("An exception occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
Replace placeholders with your values:
PlaceholderDescriptionExample
<your-api-key>QwenCloud API keysk-xxxxxxxx
Qwen-LiveTranslate Java SDK - API reference - QwenCloud