Use the DashScope Java SDK to call Qwen-ASR-Realtime.
Prerequisites
- DashScope SDK 2.22.5 or later (Install the SDK)
- Obtain an API key
- Understand the interaction flow between client and server
Interaction modes
Qwen-ASR-Realtime supports two modes for deciding when to process audio:
| Mode | enableTurnDetection | How it works |
|---|---|---|
| VAD mode (default) | true | The server detects speech boundaries using voice activity detection (VAD) and decides when to commit the audio buffer for recognition. |
| Manual mode | false | The client controls when to commit audio by calling commit(). This gives you full control over segmentation. |
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:Java
Request parameters
Connection parameters (OmniRealtimeParam)
Set these parameters with the chained methods of the OmniRealtimeParam class.
Click to view sample code
Click to view sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | The model to use. Example: qwen3-asr-flash-realtime. |
url | String | Yes | The 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. |
apikey | String | No | The API key. |
Session configuration (OmniRealtimeConfig)
Set these parameters with the chained methods of the OmniRealtimeConfig class.
Click to view sample code
Click to view sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
modalities | List<OmniRealtimeModality> | Yes | Output modality. Fixed to [OmniRealtimeModality.TEXT]. |
enableTurnDetection | boolean | No | Enables server-side VAD. When disabled, call commit() to trigger recognition manually. Default: true. |
turnDetectionType | String | No | VAD type. Fixed to server_vad. |
turnDetectionThreshold | float | No | VAD 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. |
turnDetectionSilenceDurationMs | int | No | Silence 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. |
transcriptionConfig | OmniRealtimeTranscriptionParam | No | Speech recognition settings. See Transcription parameters. |
Transcription parameters (OmniRealtimeTranscriptionParam)
Set these parameters with the setter methods of the OmniRealtimeTranscriptionParam class.
Click to view sample code
Click to view sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
language | String | No | Language of the audio source. For supported languages, see Supported languages. |
inputSampleRate | int | No | Audio 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). |
inputAudioFormat | String | No | Audio encoding format. Valid values: pcm, opus. Default: pcm. |
corpusText | String | No | Context 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
Connect to the server
NoApiKeyException, InterruptedException.
Configure the session
Send audio data
- 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 callcommit()to trigger recognition. Each event can contain up to 15 MiB of audio data.
Commit the audio buffer
This method is only available in manual mode (enableTurnDetection=false). An error occurs if the audio buffer is empty.
End the session
- VAD mode: After you finish sending audio.
- Manual mode: After you call
commit().
Close the connection
Get session and response IDs
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.
| Method | Parameters | Triggered when |
|---|---|---|
onOpen() | None | The 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. |