Prerequisites
- The service is activated and Obtain an API key. To guard against security risks caused by code leaks, Configure API key as an environment variable, rather than hard-coding it in your code.
- Install the latest DashScope SDK.
Quick start
Use the same examples for the models below. Replace the model ID using this table.
| Model | Model ID in the example |
|---|---|
| Qwen-Audio-ASR-Streaming | Non-streaming and callback (local file) — qwen-audio-3.1-asr-flash-streamingCallback (microphone) and Flowable — qwen-audio-3.0-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message |
| Fun-ASR-Realtime | fun-asr-realtime |
- Synchronous call: recognizes a local file and returns the complete result at once. Best for processing pre-recorded audio.
- Bidirectional streaming call: recognizes an audio stream directly and returns results in real time. The audio stream can come from an external device, such as a microphone, or be read from a local file. Best for scenarios that require immediate feedback.
- Synchronous call
- Bidirectional streaming call: callback-based
- Bidirectional streaming call: Flowable-based
call method to bind Request parameters and the file to recognize. The method performs recognition and returns the final result.High-concurrency calls
The DashScope Java SDK uses the connection pooling of OkHttp3 to reduce the overhead of repeatedly establishing connections. For details, see High-concurrency best practices.
Request parameters
Qwen-Audio-ASR-Streaming
Shared reference
Use the chained methods of RecognitionParam to configure the model, sample rate, audio format, and other parameters. Pass the configured parameter object to the call/streamCall method of The Recognition class.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | The model name. |
sampleRate | Integer | Yes | The sample rate in Hz. Any sample rate is supported. |
format | String | Yes | The audio format.Valid values:
|
keep_dialect | boolean | No | Supported by qwen-audio-3.1-asr-flash-streaming only. Defaults to false, which transcribes dialects into standard Chinese. Set to true to preserve dialect expressions. Set with .parameter("keep_dialect", value). See Client events for details. |
vad_model | String | No | Supported by qwen-audio-3.1-asr-flash-streaming only. Set to near_meeting_16k (near-field) or far_field_meeting_16k (far-field, default). Set with .parameter("vad_model", value). See Client events for details. |
vocabularyId | String | No | The ID of a precompiled hot word list.Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list.Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests.For usage details, see Precompiled hotwords. |
vocabulary | Map<String, Integer> | No | Instant hot words.Passed as key-value pairs, where the key is the hot word text (string) and the value is the hot word weight (integer). No hot word list needs to be created in advance. The weight ranges from [1, 5] or is set to 50: a value in [1, 5] makes the model more likely to output the word as the value increases; a value of 50 designates a super hot word, which greatly improves recall, but the number of super hot words cannot exceed 50.Suitable for temporary, session-level hot word optimization.When instant and precompiled hotwords are configured together, the system merges both sets. If the merged set contains more than 2000 hotwords, the system randomly selects 2000 to use. For usage details, see Instant hotwords.Set vocabulary through the parameter method or the parameters method of the RecognitionParam instance: |
max_sentence_silence | Integer | No | The VAD silence threshold for segmentation, in ms. When the silence after a segment of speech exceeds this threshold, the system determines that the sentence has ended.Default value: 800.Valid values: [200, 6000].Set max_sentence_silence through the parameter method or the parameters method of the RecognitionParam instance: |
multi_threshold_mode_enabled | boolean | No | Whether to enable multi-threshold mode. When enabled, this prevents VAD segments from becoming too long.Default value: false.Set multi_threshold_mode_enabled through the parameter method or the parameters method of the RecognitionParam instance: |
punctuation_prediction_enabled | boolean | No | Sets whether to automatically add punctuation to the recognition results:
punctuation_prediction_enabled through the parameter method or the parameters method of the RecognitionParam instance: |
heartbeat | boolean | No | Whether to enable heartbeat packets.Default value: false.
To use this field, the SDK version must be 2.19.1 or later. heartbeat through the parameter method or the parameters method of the RecognitionParam instance: |
language_hints | String[] | No | The language of the audio to recognize. There is no default value; if not set, the model detects the language automatically.You can set up to 4 values. If you set more, only the first 4 take effect.
Click to view the supported language codes
language_hints through the parameter method or the parameters method of the RecognitionParam instance: |
speech_noise_threshold | float | No | The threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD).Valid values: [-1.0, 1.0].Value descriptions:
speech_noise_threshold through the parameter method or the parameters method of the RecognitionParam instance: |
special_word_filter | String | No | Specifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering.Set special_word_filter through the parameter method or the parameters method of the RecognitionParam instance: |
input | Map<String, Object> | No | Input object that passes in the conversation context. The context helps recognition and improves the recognition accuracy of proper terms. For usage, see Quick start.The Map must contain a context key whose value is a message array of type List<Map<String, Object>>. Each message contains the following fields:
To use this field, the SDK version must be 2.22.23 or later. input through the input method of the RecognitionParam instance: |
apiKey | String | No | Your API key. |
Qwen-Audio-ASR-Message
Shared reference
Use the chained methods of RecognitionParam to configure the model, sample rate, audio format, and other parameters. Pass the configured parameter object to the call/streamCall method of The Recognition class.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | The model name. Set to qwen-audio-3.1-asr-flash-message. |
sampleRate | Integer | Yes | The sample rate, in Hz. Only16000 Hz is supported. |
format | String | Yes | The audio format. Valid values:
|
disfluency_removal_enabled | boolean | No | Whether to filter filler words and polish the output. Defaults to false. Set to true to enable this feature. Set with .parameter("disfluency_removal_enabled", value). |
intermediate_result_enabled | boolean | No | Whether to return intermediate streaming results. Defaults to false. Set to true to return intermediate streaming results. Set with .parameter("intermediate_result_enabled", value). |
keep_dialect | boolean | No | Defaults to false, which transcribes dialects into standard Chinese. Set to true to preserve dialect expressions. Set with .parameter("keep_dialect", value). See Client events for details.This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false). |
vad_model | String | No | Set to near_meeting_16k (near-field) or far_field_meeting_16k (far-field, default). Set with .parameter("vad_model", value). See Client events for details. |
vocabularyId | String | No | The ID of a precompiled hot word list. Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list.Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests.For usage details, see Precompiled hotwords. |
vocabulary | Map<String, Integer> | No | Instant hot words. Passed as key-value pairs, where the key is the hot word text (string) and the value is the hot word weight (integer). No hot word list needs to be created in advance. The weight ranges from [1, 5] or is set to 50: a value in [1, 5] makes the model more likely to output the word as the value increases; a value of 50 designates a super hot word, which greatly improves recall, but the number of super hot words cannot exceed 50.Suitable for temporary, session-level hot word optimization.When instant and precompiled hotwords are configured together, the system merges both sets. If the merged set contains more than 2000 hotwords, the system randomly selects 2000 to use. For usage details, see Instant hotwords.Set vocabulary through the parameter method or the parameters method of the RecognitionParam instance: |
language_hints | String[] | No | The language of the audio to recognize. There is no default value; if not set, the model detects the language automatically.You can set up to 4 values. If you set more, only the first 4 take effect.
Click to view the supported language codes
.parameter("language_hints", new String[]{"zh"}) on RecognitionParam.This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false). |
max_sentence_silence | Integer | No | The VAD silence threshold for segmentation, in ms. When the silence after a segment of speech exceeds this threshold, the system determines that the sentence has ended. Default value: 800.Valid values: [200, 6000].Setmax_sentence_silence through the parameter method or the parameters method of the RecognitionParam instance: |
heartbeat | boolean | No | Whether to enable heartbeat packets. Default value: false.
To use this field, the SDK version must be 2.19.1 or later. heartbeat through the parameter method or the parameters method of the RecognitionParam instance: |
speech_noise_threshold | float | No | The threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD). Valid values: [-1.0, 1.0].Value descriptions:
speech_noise_threshold through the parameter method or the parameters method of the RecognitionParam instance: |
input | Map<String, Object> | No | Input object that passes in the conversation context. The context helps recognition and improves the recognition accuracy of proper terms. For usage, see Quick start. The Map must contain acontext key whose value is a message array of type List<Map<String, Object>>. Each message contains the following fields:
To use this field, the SDK version must be 2.22.23 or later. input through the input method of the RecognitionParam instance: |
apiKey | String | No | Your API key. |
Fun-ASR-Realtime
Shared reference
Use the chained methods of RecognitionParam to configure the model, sample rate, audio format, and other parameters. Pass the configured parameter object to the call/streamCall method of The Recognition class.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | String | Yes | The model name. |
sampleRate | Integer | Yes | The sample rate, in Hz.Valid values: 8 kHz models support only 8000 Hz; other models support any sample rate. |
format | String | Yes | The audio format.Valid values:
|
vocabularyId | String | No | The ID of a precompiled hot word list.Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list.Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests.For usage details, see Precompiled hotwords. |
max_sentence_silence | Integer | No | The VAD silence threshold for segmentation, in ms. When the silence after a segment of speech exceeds this threshold, the system determines that the sentence has ended.Default value: 1300.Valid values: [200, 6000].Set max_sentence_silence through the parameter method or the parameters method of the RecognitionParam instance: |
multi_threshold_mode_enabled | boolean | No | Whether to enable multi-threshold mode. When enabled, this prevents VAD segments from becoming too long.Default value: false.Set multi_threshold_mode_enabled through the parameter method or the parameters method of the RecognitionParam instance: |
punctuation_prediction_enabled | boolean | No | Sets whether to automatically add punctuation to the recognition results:
punctuation_prediction_enabled through the parameter method or the parameters method of the RecognitionParam instance: |
heartbeat | boolean | No | Whether to enable heartbeat packets.Default value: false.
To use this field, the SDK version must be 2.19.1 or later. heartbeat through the parameter method or the parameters method of the RecognitionParam instance: |
language_hints | String[] | No | The language of the audio to recognize. There is no default value; if not set, the model detects the language automatically.You can set 1 value. If you set more, only the first value takes effect.
Click to view the supported language codes
language_hints through the parameter method or the parameters method of the RecognitionParam instance: |
speech_noise_threshold | float | No | The threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD).Valid values: [-1.0, 1.0].Value descriptions:
speech_noise_threshold through the parameter method or the parameters method of the RecognitionParam instance: |
special_word_filter | String | No | Specifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering.Set special_word_filter through the parameter method or the parameters method of the RecognitionParam instance: |
input | Map<String, Object> | No | Input object that passes in the conversation context. The context helps recognition and improves the recognition accuracy of proper terms. For usage, see Quick start.The Map must contain a context key whose value is a message array of type List<Map<String, Object>>. Each message contains the following fields:
To use this field, the SDK version must be 2.22.23 or later. input through the input method of the RecognitionParam instance: |
apiKey | String | No | Your API key. |
API reference
Qwen-Audio-ASR-Streaming / Fun-ASR-Realtime
The Recognition class
Import Recognition with import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Its key interfaces are as follows:
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | Callback-based streaming real-time recognition. This method does not block the current thread. | |
| The recognition result. | Non-streaming recognition of a local file. This method blocks the current thread until the entire audio file is read. The file must be readable. | |
| Flowable<RecognitionResult> | Flowable-based streaming real-time recognition. | |
| None | Sends audio. Keep each pushed audio chunk within a reasonable size. A recommended chunk holds about 100 ms of audio and is 1 KB to 16 KB in size.Recognition results are delivered through the onEvent method of the The callback interface (ResultCallback). | |
None | None | Stops real-time recognition.This method blocks the current thread until the ResultCallback callback's onComplete or onError is called. | |
| code: The WebSocket close code.reason: The reason for closing.For guidance on setting these two parameters, see The WebSocket Protocol. | true | After a task ends, always close the WebSocket connection, whether or not an exception occurred, to avoid connection leaks. To reuse connections for better efficiency, see High-concurrency best practices. | |
None | requestId | Gets the requestId of the current task. Available after a new task starts with call or streamingCall.This method is available only in SDK version 2.18.0 and later. | |
None | The first-packet latency. | Gets the first-packet latency, that is, the delay from sending the first audio packet to receiving the first recognition result. Use it after the task completes. This method is available only in SDK version 2.18.0 and later. | |
None | The last-packet latency. | Gets the last-packet latency, that is, the time from sending the stop command to receiving the final recognition result. Use it after the task completes.This method is available only in SDK version 2.18.0 and later. |
The callback interface (ResultCallback)
During bidirectional streaming calls, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information or data returned by the server.
Implement the callback methods by extending the abstract class ResultCallback. When you extend this class, you can set the generic type to RecognitionResult. RecognitionResult wraps the data structure returned by the server.
Because Java supports connection reuse, there is no onClose or onOpen.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
result: Real-time recognition result (RecognitionResult) | None | Called when the server sends a response. | |
None | None | Called after the task completes. | |
e: The exception information. | None | Called when an exception occurs. |
Real-time recognition result (RecognitionResult)
RecognitionResult represents the result of a single real-time recognition.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
None | requestId | Gets the requestId. | |
None | Whether a complete sentence has been formed, that is, whether a sentence boundary was detected. | Determines whether the given sentence has ended. | |
None | Sentence information (Sentence) | Gets the sentence information, including timestamps and text. |
Sentence information (Sentence)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
None | The sentence start time, in ms. | Returns the sentence start time. | |
None | The sentence end time, in ms. | Returns the sentence end time. | |
None | The recognized text. | Returns the recognized text. | |
None | A List of Word-level timestamp information (Word) objects. | Returns word-level timestamp information. |
Word-level timestamp information (Word)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
None | The word start time, in ms. | Returns the word start time. | |
None | The word end time, in ms. | Returns the word end time. | |
None | The word. | Returns the recognized word. | |
None | The punctuation. | Returns the punctuation. |
Qwen-Audio-ASR-Streaming
Key interfaces
Response
- Real-time recognition result (RecognitionResult)
- Sentence information (
Sentence) - Word-level timestamp information (Word)
Qwen-Audio-ASR-Message
Key interfaces
The Recognition class
Import Recognition with import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Its key interfaces are as follows:
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | Callback-based streaming real-time recognition. This method does not block the current thread. | |
| The recognition result. | Non-streaming recognition of a local file. This method blocks the current thread until the entire audio file is read. The file must be readable. | |
| Flowable<RecognitionResult> | Flowable-based streaming real-time recognition. | |
| None | Sends audio. Keep each pushed audio chunk within a reasonable size. A recommended chunk holds about 100 ms of audio and is 1 KB to 16 KB in size. Recognition results are delivered through the onEvent method of the The callback interface (ResultCallback). | |
| None | None | Stops real-time recognition. This method blocks the current thread until theResultCallback callback's onComplete or onError is called. | |
code: The WebSocket close code. reason: The reason for closing.For guidance on setting these two parameters, see The WebSocket Protocol. | true | After a task ends, always close the WebSocket connection, whether or not an exception occurred, to avoid connection leaks. To reuse connections for better efficiency, see High-concurrency best practices. | |
| None | requestId | Gets the requestId of the current task. Available after a new task starts with This method is available only in SDK version 2.18.0 and later. | |
| None | The first-packet latency. | Gets the first-packet latency, that is, the delay from sending the first audio packet to receiving the first recognition result. Use it after the task completes. This method is available only in SDK version 2.18.0 and later. | |
| None | The last-packet latency. | Gets the last-packet latency, that is, the time from sending the This method is available only in SDK version 2.18.0 and later. |
Update conversation context
CallupdateContext to update conversation context while a recognition task is running. The context is used to assist recognition of subsequent audio. This method requires DashScope Java SDK 2.23.0 or later.
- When to call: After starting streaming recognition with
call(param, callback)and before callingstop. - Parameter:
payloadInputis aMap<String, Object>containing thepayload.inputobject of acontinue-taskevent, including thecontextfield. Do not add an extrapayloadorinputwrapper. - Supported models and parameter constraints: See continue-task.
recognizer instance. Import the Java collection types with import java.util.*;.
The callback interface (ResultCallback)
During bidirectional streaming calls, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information or data returned by the server.
Implement the callback methods by extending the abstract class ResultCallback. When you extend this class, you can set the generic type to RecognitionResult. RecognitionResult wraps the data structure returned by the server.
Because Java supports connection reuse, there is no onClose or onOpen.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
result: Real-time recognition result (RecognitionResult) | None | Called when the server sends a response. | |
| None | None | Called after the task completes. | |
e: The exception information. | None | Called when an exception occurs. |
Response
Real-time recognition result (RecognitionResult)
RecognitionResult represents the result of a single real-time recognition.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | requestId | Gets the requestId. | |
| None | Whether a complete sentence has been formed, that is, whether a sentence boundary was detected. | Determines whether the given sentence has ended. | |
| None | Sentence information (Sentence) | Gets the sentence information, including timestamps and text. |
Sentence information (Sentence)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | The sentence start time, in ms. | Returns the sentence start time. | |
| None | The sentence end time, in ms. | Returns the sentence end time. | |
| None | The recognized text. | Returns the recognized text. | |
| None | A List of Word-level timestamp information (Word) objects. | Returns word-level timestamp information. |
Word-level timestamp information (Word)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | The word start time, in ms. | Returns the word start time. | |
| None | The word end time, in ms. | Returns the word end time. | |
| None | The word. | Returns the recognized word. | |
| None | The punctuation. | Returns the punctuation. |
Fun-ASR-Realtime
Key interfaces
Response
- Real-time recognition result (RecognitionResult)
- Sentence information (
Sentence) - Word-level timestamp information (Word)