Skip to main content
SDK access

Qwen-ASR-Realtime Java SDK - API reference

Use the DashScope Java SDK to call Qwen-ASR-Realtime.

Prerequisites

Interaction modes

Qwen-ASR-Realtime supports two modes for deciding when to process audio:
ModeenableTurnDetectionHow it works
VAD mode (default)trueThe server detects speech boundaries using voice activity detection (VAD) and decides when to commit the audio buffer for recognition.
Manual modefalseThe client controls when to commit audio by calling commit(). This gives you full control over segmentation.
For details on each mode, see VAD mode and Manual mode.

Complete example

The example code reads your_audio_file.pcm (PCM16, 16 kHz, mono). If you only have an MP3, WAV, or similar format, convert it with ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
Java
import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.util.Base64;
import java.util.Collections;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;

public class Qwen3AsrRealtimeUsage {
    private static final Logger log = LoggerFactory.getLogger(Qwen3AsrRealtimeUsage.class);
    private static final int AUDIO_CHUNK_SIZE = 1024; // Audio chunk size in bytes
    private static final int SLEEP_INTERVAL_MS = 30;  // Sleep interval in milliseconds

    public static void main(String[] args) throws InterruptedException, LineUnavailableException {
        CountDownLatch finishLatch = new CountDownLatch(1);

        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3-asr-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")
                // If you have not configured the environment variable, replace the following line with your QwenCloud API Key: .apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        OmniRealtimeConversation conversation = null;
        final AtomicReference<OmniRealtimeConversation> conversationRef = new AtomicReference<>(null);
        conversation = new OmniRealtimeConversation(param, new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("connection opened");
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        System.out.println("start session: " + message.get("session").getAsJsonObject().get("id").getAsString());
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        System.out.println("transcription: " + message.get("transcript").getAsString());
                        finishLatch.countDown();
                        break;
                    case "input_audio_buffer.speech_started":
                        System.out.println("======VAD Speech Start======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("======VAD Speech Stop======");
                        break;
                    case "conversation.item.input_audio_transcription.text":
                        System.out.println("transcription: " + message.get("text").getAsString() + message.get("stash").getAsString());
                        break;
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                System.out.println("connection closed code: " + code + ", reason: " + reason);
            }
        });
        conversationRef.set(conversation);
        try {
            conversation.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }

        OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
        transcriptionParam.setLanguage("zh");
        transcriptionParam.setInputAudioFormat("pcm");
        transcriptionParam.setInputSampleRate(16000);

        OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .transcriptionConfig(transcriptionParam)
                .build();
        conversation.updateSession(config);

        String filePath = "your_audio_file.pcm";
        File audioFile = new File(filePath);
        if (!audioFile.exists()) {
            log.error("Audio file not found: {}", filePath);
            return;
        }

        try (FileInputStream audioInputStream = new FileInputStream(audioFile)) {
            byte[] audioBuffer = new byte[AUDIO_CHUNK_SIZE];
            int bytesRead;
            int totalBytesRead = 0;

            log.info("Starting to send audio data from: {}", filePath);

            // Read and send audio data in chunks
            while ((bytesRead = audioInputStream.read(audioBuffer)) != -1) {
                totalBytesRead += bytesRead;
                String audioB64 = Base64.getEncoder().encodeToString(audioBuffer);
                // Send audio chunk to conversation
                conversation.appendAudio(audioB64);

                // Add small delay to simulate real-time audio streaming
                Thread.sleep(SLEEP_INTERVAL_MS);
            }

            log.info("Finished sending audio data. Total bytes sent: {}", totalBytesRead);

        } catch (Exception e) {
            log.error("Error sending audio from file: {}", filePath, e);
        }

        //send session.finish and wait for finish and close
        conversation.endSession();
        log.info("task finished");

        System.exit(0);
    }
}
        Constants.baseHttpApiUrl = "https://ap-southeast-1.maas.qwencloudapi.com/api/v1";

Request parameters

Connection parameters (OmniRealtimeParam)

Set these parameters with the chained methods of the OmniRealtimeParam class.
OmniRealtimeParam param = OmniRealtimeParam.builder()
        .model("qwen3-asr-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")
        // To obtain an API key, see https://docs.qwencloud.com/api-reference/preparation/api-key
        // If you have not configured an environment variable, replace the following line with .apikey("sk-xxx").
        .apikey(System.getenv("DASHSCOPE_API_KEY"))
        .build();
ParameterTypeRequiredDescription
modelStringYesThe model to use. Example: qwen3-asr-flash-realtime.
urlStringYesThe service endpoint. Singapore: wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime. China North 2 (Beijing): wss://cn-beijing.maas.qwencloudapi.com/api-ws/v1/realtime. For other regions, replace ap-southeast-1 with the region code. See Regions.
apikeyStringNoThe API key.

Session configuration (OmniRealtimeConfig)

Set these parameters with the chained methods of the OmniRealtimeConfig class.
OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
        .enableTurnDetection(true)
        .turnDetectionType("server_vad")
        .turnDetectionThreshold(0.0f)
        .turnDetectionSilenceDurationMs(400)
        .transcriptionConfig(transcriptionParam)
        .build();
ParameterTypeRequiredDescription
modalitiesList<OmniRealtimeModality>YesOutput modality. Fixed to [OmniRealtimeModality.TEXT].
enableTurnDetectionbooleanNoEnables server-side VAD. When disabled, call commit() to trigger recognition manually. Default: true.
turnDetectionTypeStringNoVAD type. Fixed to server_vad.
turnDetectionThresholdfloatNoVAD sensitivity threshold. Recommended value: 0.0.
Default: 0.2. Valid range: [-1, 1].
Lower values increase sensitivity (may trigger on background noise). Higher values reduce sensitivity and help avoid false triggers in noisy environments.
turnDetectionSilenceDurationMsintNoSilence duration in milliseconds that marks the end of an utterance. Recommended value: 400.
Default: 800. Valid range: [200, 6000].
Shorter durations (e.g., 300 ms) speed up responses but may split natural pauses. Longer durations (e.g., 1200 ms) handle pauses better but increase latency.
transcriptionConfigOmniRealtimeTranscriptionParamNoSpeech recognition settings. See Transcription parameters.

Transcription parameters (OmniRealtimeTranscriptionParam)

Set these parameters with the setter methods of the OmniRealtimeTranscriptionParam class.
OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
transcriptionParam.setLanguage("zh");
transcriptionParam.setInputSampleRate(16000);
transcriptionParam.setInputAudioFormat("pcm");
ParameterTypeRequiredDescription
languageStringNoLanguage of the audio source. For supported languages, see Supported languages.
inputSampleRateintNoAudio sampling rate in Hz. Valid values: 16000, 8000.
Default: 16000.
Setting 8000 causes server-side upsampling to 16,000 Hz, which may introduce minor latency. Use only for natively 8,000 Hz audio (e.g., telephony).
inputAudioFormatStringNoAudio encoding format. Valid values: pcm, opus. Default: pcm.
corpusTextStringNoContext text for contextual biasing. Provide background text, entity vocabularies, or reference material to improve recognition accuracy. Maximum: 10,000 tokens.

Key interfaces

OmniRealtimeConversation

Import: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation This class manages the WebSocket lifecycle: connecting to the server, sending audio, and ending the session.

Create a conversation

OmniRealtimeConversation conversation =
        new OmniRealtimeConversation(param, callback);
Creates a new conversation instance with the specified connection parameters and callback handler.

Connect to the server

conversation.connect();
Opens a WebSocket connection. The server responds with session.created and session.updated events. Throws: NoApiKeyException, InterruptedException.

Configure the session

conversation.updateSession(config);
Updates the session configuration after the connection is established. The server responds with a session.updated event. If not called, the server uses default settings.

Send audio data

conversation.appendAudio(audioBase64);
Appends a Base64-encoded audio segment to the server-side audio buffer.
  • VAD mode (enableTurnDetection=true): The server detects speech boundaries and decides when to process the buffer.
  • Manual mode (enableTurnDetection=false): Audio accumulates in the buffer until you call commit() to trigger recognition. Each event can contain up to 15 MiB of audio data.

Commit the audio buffer

conversation.commit();
Submits the buffered audio for recognition. The server responds with an input_audio_buffer.committed event.
This method is only available in manual mode (enableTurnDetection=false). An error occurs if the audio buffer is empty.

End the session

conversation.endSession();  // synchronous
// or
conversation.endSessionAsync();  // asynchronous
Notifies the server to finish processing any remaining audio and end the session. The server responds with a session.finished event. When to call:
  • VAD mode: After you finish sending audio.
  • Manual mode: After you call commit().

Close the connection

conversation.close();
Stops the task and closes the WebSocket connection immediately.

Get session and response IDs

String sessionId = conversation.getSessionId();
String responseId = conversation.getResponseId();
  • getSessionId() returns the session ID for the current task.
  • getResponseId() returns the response ID of the most recent server response.

OmniRealtimeCallback

Import: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback Inherit this class and implement the callback methods to handle server events.
MethodParametersTriggered when
onOpen()NoneThe WebSocket connection is established.
onEvent(JsonObject message)message: A server event as JSON. Common event types: session.created, session.updated, input_audio_buffer.committed, conversation.item.input_audio_transcription.completed, session.finished.A server event is received. Parse the type field to determine the event type.
onClose(int code, String reason)code: Status code. reason: Reason for closing.The WebSocket connection is closed.
Qwen-ASR-Realtime Java SDK - API reference - QwenCloud