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

The sample rate, in Hz.

Only 16000 Hz is supported.

The audio format.

Valid values:

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

This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false).

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.

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:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# Instant hot words are passed in through parameters
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)

You can set up to 4 values. If you set more, only the first 4 take effect.

Pass it as a keyword argument with the same name.

This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false).

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

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 was introduced in SDK 1.23.1 and is already included in version 2.0.1 and later.

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

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

# 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 input parameter when creating the recognition session
      recognition = client.audio.asr.recognize(
          model='qwen-audio-3.1-asr-flash-message',
          format='wav',
          sample_rate=16000,
          input=input_context,
      )

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

Creates a bidirectional streaming recognition session. Entering the with context automatically calls start to establish the connection and submit the task.

Sending audio and consuming events must run concurrently (use it together with send_audio_frame, events()/results(), and stop).

recognize_file

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

A non-streaming call based on a local file: it automatically sends the audio in chunks, drives the task to completion, and yields server events one by one. This method requires read permission on the file.

start

def start(self)

Starts speech recognition: establishes the connection, submits the task, and waits for task-started. It is called automatically when the with context is entered, and audio can only be sent after it succeeds.

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 event iteration (events()/results()).

stop

def stop(self)

Stops speech recognition: it only notifies the server that the input is finished; the receiver thread must keep consuming events() until the task-finished event.

events / results

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

Iterates server events: events() yields raw event dicts (the recognized text is in payload.output.sentence); results() yields only recognition result frames and returns typed Recognition result (RecognitionResult) objects (heartbeat frames are filtered out).

close

def close(self)

Closes the recognition session. Called automatically when the with context is exited.

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response

Gets the request_id, the first-packet delay (the latency from sending the first audio packet to receiving the first recognition result), and the last-packet delay (the time from sending the stop command to the last recognition result arriving). Use them after the task completes. last_response is the last successfully read raw message, which you can use to retrieve a task-failed error. They remain readable after the session is closed.

event["header"]["event"] == "task-started"

task-started event

None

Read internally by start() and stored in last_response when it returns; it is not yielded again by events().

def events(self) -> Iterator[Dict]

event: a server event dict

Iterator

Yields events when the server responds. Recognition results are in payload.output.sentence and may be heartbeat or empty-text events, which applications can ignore as needed. Consume it with a single receiver thread; do not create multiple concurrent readers.

def results(self) -> Iterator[RecognitionResult]

result: recognition result (RecognitionResult)

Iterator

Yields only recognition result frames (heartbeat frames are filtered out), and iteration ends after all recognition results are returned.

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

DashScopeError exception

None

Raised in the sending/receiving thread when an error occurs; catch it with try/except.

event["header"]["event"] == "task-finished"

task-finished event

None

Yielded by events() after the server completes all recognition, after which iteration ends; you must still read this event after calling stop().

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

Gets the current recognized sentence and its timestamp information. This method returns Dict[str, Any] (a single sentence).

For details, see Sentence (Sentence).

result.request_id

def is_sentence_end(self) -> bool