All Products
Search
Document Center

Alibaba Cloud Model Studio:Qwen-Audio-ASR-Message Python SDK

Last Updated:Sep 24, 2026

This topic describes the parameters and interfaces of the Python SDK for the Qwen-Audio-3.1-ASR-Flash-Message real-time speech recognition model.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Prerequisites

Quick start

The Recognition class provides interfaces for both non-streaming and bidirectional streaming calls. Choose the call method that fits your needs:

  • Non-streaming call: Recognizes a local file and returns the complete result in a single response. Suitable for processing pre-recorded audio.
  • Bidirectional streaming call: Recognizes an audio stream directly and outputs results in real time. The audio stream can come from an external device, such as a microphone, or be read from a local file. Suitable for scenarios that require immediate feedback.

Non-streaming call

Submit a single real-time speech recognition task and get the recognition result synchronously by passing in a local file.

Instantiate a Recognition class, bind a Request parameters, and call call to run recognition or translation and get the final Recognition result (RecognitionResult).

from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

recognition = Recognition(model='qwen-audio-3.1-asr-flash-message',
                          format='wav',
                          sample_rate=16000,
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    print('Recognition result:')
    print(result.get_sentence())
else:
    print('Error: ', result.message)

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

Bidirectional streaming call

Submit a single real-time speech recognition task and stream the real-time recognition results by implementing the callback interface.

  1. Start streaming speech recognition.

    Instantiate a Recognition class, bind a Request parameters and a Callback interface (RecognitionCallback), and call the start method to start streaming speech recognition.

  2. Stream the audio.

    Call the send_audio_frame method of the Recognition class in a loop to send the binary audio stream to the server in segments. The stream is read from a local file or a device, such as a microphone.

    While the audio is being sent, the server returns recognition results to the client in real time through the on_event method of the Callback interface (RecognitionCallback).

    Send about 100 ms of audio per frame, and keep each frame between 1 KB and 16 KB.

  3. End the task.

    Call the stop method of the Recognition class to end speech recognition.

    This method blocks the current thread until the on_complete or on_error callback of the Callback interface (RecognitionCallback) is triggered.

import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from dashscope.audio.asr import *

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # sampling rate (Hz)
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition callback
class Callback(RecognitionCallback):
    def on_open(self) -> None:
        global mic
        global stream
        print('RecognitionCallback open.')
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)

    def on_close(self) -> None:
        global mic
        global stream
        print('RecognitionCallback close.')
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

    def on_complete(self) -> None:
        print('RecognitionCallback completed.')  # recognition completed

    def on_error(self, message) -> None:
        print('RecognitionCallback task_id: ', message.request_id)
        print('RecognitionCallback error: ', message.message)
        # Stop and close the audio stream if it is running
        if 'stream' in globals() and stream.active:
            stream.stop()
            stream.close()
        # Forcefully exit the program
        sys.exit(1)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print('RecognitionCallback text: ', sentence['text'])
            if RecognitionResult.is_sentence_end(sentence):
                print(
                    'RecognitionCallback sentence end, request_id:%s, usage:%s'
                    % (result.get_request_id(), result.get_usage(sentence)))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.get_last_request_id(),
            recognition.get_first_package_delay(),
            recognition.get_last_package_delay(),
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    # The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

    # The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
    dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

    # Create the recognition callback
    callback = Callback()

    # Call recognition service by async mode, you can customize the recognition parameters, like model, format,
    # sample_rate
    recognition = Recognition(
        model='qwen-audio-3.1-asr-flash-message',
        format=format_pcm,
        # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
        sample_rate=sample_rate,
        # only supports 16000 Hz
        callback=callback)

    # Start recognition
    recognition.start()

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")
    # Create a keyboard listener until "Ctrl+C" is pressed

    while True:
        if stream:
            data = stream.read(3200, exception_on_overflow=False)
            recognition.send_audio_frame(data)
        else:
            break

    recognition.stop()
import os
import time
import dashscope
from dashscope.audio.asr import *

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

class Callback(RecognitionCallback):
    def on_complete(self) -> None:
        print(get_timestamp() + ' Recognition completed')  # recognition complete

    def on_error(self, message: str) -> None:
        print('Error occurred: ', message)
        print('Error details: ', message)
        exit(0)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print(get_timestamp() + ' RecognitionCallback text: ', sentence['text'])
        if RecognitionResult.is_sentence_end(sentence):
            print(get_timestamp() +
                  'RecognitionCallback sentence end, request_id:%s, usage:%s'
                  % (result.get_request_id(), result.get_usage(sentence)))

callback = Callback()

recognition = Recognition(model='qwen-audio-3.1-asr-flash-message',
                          format='wav',
                          sample_rate=16000,
                          callback=callback)

try:
    audio_data: bytes = None
    f = open("{YOUR_AUDIO_FILE}", 'rb')
    if os.path.getsize("{YOUR_AUDIO_FILE}"):
        # Read all the file data into the buffer at once
        file_buffer = f.read()
        f.close()
        print("Start Recognition")
        recognition.start()

        # Send 3200 bytes from the buffer at a time
        buffer_size = len(file_buffer)
        offset = 0
        chunk_size = 3200

        while offset < buffer_size:
            # Calculate the size of the data chunk to send this time
            remaining_bytes = buffer_size - offset
            current_chunk_size = min(chunk_size, remaining_bytes)

            # Extract the current data chunk from the buffer
            audio_data = file_buffer[offset:offset + current_chunk_size]

            # Send the audio data frame
            recognition.send_audio_frame(audio_data)
            # Update the offset
            offset += current_chunk_size

            # Add a delay to simulate real-time transmission
            time.sleep(0.1)

        recognition.stop()
    else:
        raise Exception(
            'The supplied file was empty (zero bytes long)')
except Exception as e:
    raise e

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

Request parameters

Set request parameters through the constructor (init) of the Recognition class.

ParameterTypeRequiredDescription
modelstrYesThe model name. Set to qwen-audio-3.1-asr-flash-message.
sample_rateintYes

The sample rate, in Hz.

Only 16000 Hz is supported.

formatstrYes

The audio format.

Valid values:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importantopus/speex: Must use Ogg encapsulation.

wav: Must use PCM encoding.

amr: Only the AMR-NB type is supported.

disfluency_removal_enabledboolNoWhether to filter filler words and polish the output. Defaults to false. Set to true to enable this feature. Pass as a keyword argument with the same name.
intermediate_result_enabledboolNoWhether to return intermediate streaming results. Defaults to false. Set to true to return intermediate streaming results. Pass as a keyword argument with the same name.
keep_dialectboolNoDefaults to false, which transcribes dialects into standard Chinese. Set to true to preserve dialect expressions. Pass as a keyword argument with the same name. See Client events for details.
vad_modelstrNoSet to near_meeting_16k (near-field) or far_field_meeting_16k (far-field, default). Pass as a keyword argument with the same name. See Client events for details.
vocabulary_idstrNo

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.

vocabularydictNo

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.

Example:

from dashscope.audio.asr import Recognition

vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = Recognition(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    vocabulary=vocab,
    callback=None)
max_sentence_silenceintNo

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].

heartbeatboolNo

Whether to enable heartbeat packets.

Default: False.

  • True: Keeps the connection to the server alive while silent audio is sent continuously.
  • False (default): Even when silent audio is continuously sent, the connection times out and closes after a period of time.

Silent audio refers to content in an audio file or data stream that contains no sound signal. You can generate silent audio in several ways, such as using audio editing software like Audacity or Adobe Audition, or using a command-line tool like FFmpeg.

This field requires SDK version 1.23.1 or later.

speech_noise_thresholdfloatNo

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:

  • The closer the value is to -1: The noise threshold decreases, so noise is more likely to be recognized as speech, which may cause more noise to be transcribed.
  • The closer the value is to +1: The noise threshold increases, so speech is more likely to be misjudged as noise, which may cause some speech to be filtered out.

This is an advanced configuration parameter. Adjusting it can significantly affect recognition results. Recommendations:

  • Thoroughly test and verify the results before adjusting.
  • Adjust in small increments based on the actual audio environment (a step of 0.1 is recommended).
callbackRecognitionCallbackNoCallback interface (RecognitionCallback).

Pass the following parameters as keyword arguments to the call or start method of the Recognition instance.

ParameterTypeRequiredDescription
raw_inputdictNo

The input object used to pass in the conversation context. Context enhancement improves recognition accuracy for domain-specific terms. For usage, see Quick start.

The dict must include a context key whose value is a list of messages (list[dict]). Each message contains the following fields:

  • role (str, required): The message role. user represents the recognition results from previous user turns or a domain-specific word list. assistant represents the large language model responses from previous turns.
  • content (list[dict], required): The list of message content. Each element contains type (str; set to input_text when role is user, and text when role is assistant) and text (str, the text content).

ImportantContext messages of the input_text and text types are each limited to 5 messages. When the limit is exceeded, only the 5 most recent messages are retained. The total text length per context turn cannot exceed 400 characters, and any excess is truncated from the end.

ImportantWhen you pass context, the messages in context must follow a specific order: context messages must be arranged by conversation turn, and within each turn, the user message (input_text type) must precede its corresponding assistant message (text type).

NoteThis field requires SDK version 1.25.23 or later.

# Build the input to pass in
      input_context = {
          "context": [
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "input_text",
                          "text": "Hello there"
                      }
                  ]
              },
              {
                  "role": "assistant",
                  "content": [
                      {
                          "type": "text",
                          "text": "Hello, I am Qwen. How can I help you?"
                      }
                  ]
              }
          ]
      }

      # Pass it in through the raw_input parameter
      recognition.start(raw_input=input_context)
      # Or
      recognition.call(file='{YOUR_AUDIO_FILE}', raw_input=input_context)

Key interfaces

Recognition class

Import Recognition with from dashscope.audio.asr import *.

Member methodMethod signatureDescription
call
def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult

A non-streaming call based on a local file. This method blocks the current thread until all audio is read, and requires read permission on the file.

The recognition result is returned as a RecognitionResult object.

start
def start(self, phrase_id: str = None, **kwargs)

Starts speech recognition.

A callback-based streaming real-time recognition. This method does not block the current thread. Use it together with send_audio_frame and stop.

send_audio_frame
def send_audio_frame(self, buffer: bytes)

Pushes audio. Keep each pushed audio frame neither too large nor too small: about 100 ms per frame, between 1 KB and 16 KB.

Recognition results are obtained through the on_event method of the Callback interface (RecognitionCallback).

stop
def stop(self)
Stops speech recognition. Blocks until the server finishes recognizing all received audio, then ends the task.
get_last_request_id
def get_last_request_id(self)
Gets the request_id. Available after the constructor is called (the object is created).
get_first_package_delay
def get_first_package_delay(self)
Gets the first-packet delay: the latency from sending the first audio packet to receiving the first recognition result. Use it after the task completes.
get_last_package_delay
def get_last_package_delay(self)
Gets the last-packet delay: the time from sending the stop command to receiving the last recognition result. Use it after the task completes.
get_response
def get_response(self)
Gets the last message. Use it to retrieve a task-failed error.

Update conversation context

Call update_context to update conversation context while a recognition task is running. The context is used to assist recognition of subsequent audio. This method requires DashScope Python SDK 1.27.5 or later.

def update_context(self, payload_input: dict)
  • When to call: After starting streaming recognition with start and before calling stop.
  • Parameter: payload_input is a dictionary containing the payload.input object of a continue-task event, including the context field. Do not add an extra payload or input wrapper.
  • Supported models and parameter constraints: See continue-task.

The following example uses an existing, started recognition instance.

payload_input = {
    "context": [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "Hello"}]
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "Hello, I am Qwen. How can I help you?"}]
        }
    ]
}
recognition.update_context(payload_input=payload_input)

Callback interface (RecognitionCallback)

During a Bidirectional streaming call, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information and data returned by the server.

class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('Connection established')

    def on_event(self, result: RecognitionResult) -> None:
        # Implement the logic to receive recognition results
        pass

    def on_complete(self) -> None:
        print('Task completed')

    def on_error(self, message: str) -> None:
        print('An error occurred:', message)

    def on_close(self) -> None:
        print('Connection closed')

callback = Callback()
MethodParameterReturn valueDescription
def on_open(self) -> None
NoneNoneCalled immediately after the connection to the server is established.
def on_event(self, result: RecognitionResult) -> None
result: Recognition result (RecognitionResult)NoneCalled when the server has a response.
def on_complete(self) -> None
NoneNoneCalled after all recognition results are returned.
def on_error(self, message: str) -> None
result: Recognition result (RecognitionResult)NoneCalled when an error occurs.
def on_close(self) -> None
NoneNoneCalled after the server closes the connection.

Response

Recognition result (RecognitionResult)

RecognitionResult represents the result of a single real-time recognition in a Bidirectional streaming call, or the result of a Non-streaming call.

Member methodMethod signatureDescription
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Gets the current recognized sentence and its timestamp information. A callback returns a single sentence, so this method returns Dict[str, Any].

For details, see Sentence (Sentence).

get_request_id
def get_request_id(self) -> str
Gets the request_id of the request.
is_sentence_end
@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool
Determines whether the given sentence has ended. This method checks whether the end_time field in sentence is None: a non-None end_time indicates that the sentence has ended. Call it as RecognitionResult.is_sentence_end(sentence), where sentence is the single-sentence dict returned by get_sentence(), not a boolean field on a Sentence instance.

Sentence information (Sentence)

The members of the Sentence class are as follows:

ParameterTypeDescription
begin_timeintSentence start time, in ms.
end_timeintSentence end time, in ms.
textstrRecognized text.
wordsA list of Word-level timestamp information (Word)Word-level timestamp information.

Word-level timestamp information (Word)

The members of the Word class are as follows:

ParameterTypeDescription
begin_timeintWord start time, in ms.
end_timeintWord end time, in ms.
textstrThe word.
punctuationstrThe punctuation.

Error codes

If you encounter errors, see Error codes for troubleshooting.

If the issue persists, join the developer community listed in the speech SDK sample repository to report your issue and provide the Request ID for further investigation.

FAQ

Features

Q: How do I keep the connection alive during long periods of silence?

Set the heartbeat request parameter to true, and keep sending silent audio to the server.

Silent audio is content in an audio file or stream that contains no sound signal. You can generate silent audio in several ways, such as using audio editing software like Audacity or Adobe Audition, or command-line tools like FFmpeg.

Q: How do I convert audio to a supported format?

Use FFmpeg. For more usage, see the FFmpeg official website.

# Basic conversion command (all-purpose template)
# -i, purpose: input file path, example value: audio.wav
# -c:a, purpose: audio codec, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar: sample rate; set to 16000 for this model
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# For example: WAV to MP3 (keep the original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 -ar 16000 -ac 1 output.mp3
# For example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 16000 -ac 1 output.wav
# For example: M4A to AAC (extract or convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Only if the source is already 16000 Hz mono AAC
ffmpeg -i input.m4a -c:a aac -b:a 64k -ar 16000 -ac 1 output.aac  # Re-encode as 16000 Hz mono audio
# For example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on -ar 16000 -ac 1 output.opus

Q: How do I recognize a local file (recording)?

There are two ways to recognize a local file:

  • Pass the local file path directly: This way returns the complete result only after recognition finishes, so it isn't suitable for scenarios that need immediate feedback.

    See Non-streaming call, and pass the file path to the call method of the Recognition class to recognize the recording directly.

  • Convert the local file to a binary stream for recognition: This way recognizes the file while streaming results, so it suits scenarios that need immediate feedback.

    See Bidirectional streaming call, and send the binary stream to the server for recognition through the send_audio_frame method of the Recognition class.

Troubleshooting

Q: Why can't the speech be recognized (no recognition result)?

  1. Check that the audio format (format) and sample rate (sampleRate/sample_rate) in the request parameters are correct and meet the parameter constraints. Common errors include:

    • The audio file has a .wav extension but is actually in MP3 format, while the format request parameter is set to wav (incorrect parameter setting).
    • The audio sample rate is 3600 Hz, but the sampleRate/sample_rate request parameter is set to 48000 (incorrect parameter setting).

    Use the ffprobe tool to get the container, codec, sample rate, channels, and other information of the audio:

    ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
    
  2. If none of the checks above reveal a problem, add custom hotwords to improve recognition of specific terms.