Alibaba Cloud Model Studio:Qwen-Audio-ASR-Filetrans non-real-time speech recognition Python SDK

model

str

Yes

The model name.

file_urls

list[str]

Yes

A list of URLs of the audio or video files to transcribe. HTTP and HTTPS are supported. A single request supports only one URL. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.

If the recording is stored in Alibaba Cloud OSS, the RESTful API supports temporary URLs prefixed with oss://, whereas the SDK does not support oss://-prefixed temporary URLs.

parameters.keep_dialect

bool

No

Supported by qwen-audio-3.1-asr-flash-filetrans only. Defaults 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 API reference for details.

parameters.vocabulary_id

str

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.

parameters.vocabulary

dict

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.

Example:

The following example reuses the client configured with the region and workspace in Quick start.

vocab = {"Zhang San": 5, "Li Si": 5}
result = client.audio.asr.jobs.create(
    model="qwen-audio-3.1-asr-flash-filetrans",
    file_urls=["{YOUR_AUDIO_URL}"],
    parameters={"vocabulary": vocab},
)

parameters.channel_id

list[int]

No

The index of the audio tracks to recognize in a multi-track audio file. The index starts at 0. For example, [0] recognizes the first track, and [0, 1] recognizes the first and second tracks at the same time. If you omit this parameter, only the first track is processed.

Default value: [0].

parameters.special_word_filter

str

No

The sensitive words to process during speech recognition. You can set a different handling method for each sensitive word. For details, see Sensitive word filtering.

parameters.diarization_enabled

bool

No

Whether to enable speaker diarization. Disabled by default.

Applies only to mono audio. Multi-channel audio does not support speaker diarization.

When enabled, the recognition result includes a speaker_id field that distinguishes different speakers.

Default value: False.

For an example of speaker_id, see Recognition result description.

parameters.speaker_count

int

No

A reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive).

By default, the number of speakers is detected automatically. If you set this value, it only guides the algorithm to output the specified count when possible and does not guarantee that exact count.

No default value.

parameters.language_hints

list[str]

No

The language codes to recognize. If you can't determine the language in advance, leave it unset and the model detects the language automatically.

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

task_id

The task ID.

status

The task status: PENDING, RUNNING, SUCCEEDED, or FAILED.

submitted_at

The submission time, corresponding to job.output["submit_time"].

scheduled_at

The processing start time, corresponding to job.output["scheduled_time"].

finished_at

The completion time, corresponding to job.output["end_time"].

output

The raw task output dictionary.

results

The subtask result list, accessible through job.results. Download the JSON file at transcription_url to retrieve the recognized text.

usage

Task usage information. qwen-audio-3.1-asr-flash-filetrans reports Token usage in input_tokens, output_tokens, and total_tokens. qwen-audio-3.0-asr-flash-filetrans is metered by duration.

code

The error code. Combine it with the message field and refer to Error codes to troubleshoot the issue.

message

The error message. Combine it with the code field and refer to Error codes to troubleshoot the issue.

task_id

Task ID.

task_status

Task status.

One of four states: PENDING, RUNNING, SUCCEEDED, and FAILED.

When a task contains multiple subtasks, the overall task status is marked as SUCCEEDED as long as any subtask succeeds. Check the subtask_status field to determine the result of each subtask.

results

Subtask recognition results.

subtask_status

Subtask status.

One of four states: PENDING, RUNNING, SUCCEEDED, and FAILED.

file_url

URL of the recognized audio.

transcription_url

URL of the audio recognition result.

The recognition result is saved as a JSON file. You can download the file from the link associated with transcription_url or read its content directly through an HTTP request. For the contents of the JSON file, see Recognition result description.

audio_format

string

The audio format of the source file.

channels

array[integer]

The track index of the audio in the source file. For single-track audio, [0] is returned; for dual-track audio, [0, 1] is returned; and so on.

original_sampling_rate

integer

The sampling rate (Hz) of the audio in the source file.

original_duration_in_milliseconds

integer

The original audio duration (ms) in the source file.

channel_id

integer

The track index of the transcription result, starting from 0.

content_duration

integer

The duration (ms) of content in the track that is identified as speech.

The speech recognition model service transcribes only the content in a track that is identified as speech, and meters and bills based on that duration. Non-speech content is not metered or billed. Typically, the speech content duration is shorter than the original audio duration. Because whether speech content exists is determined by an AI model, the result may differ slightly from the actual situation.

transcript

string

The paragraph-level transcription result.

sentences

array

The sentence-level transcription result.

words

array

The word-level transcription result.

begin_time

integer

The start timestamp (ms).

end_time

integer

The end timestamp (ms).

text

string

The transcription result.

speaker_id

integer

The index of the current speaker, starting from 0, used to distinguish between different speakers.

This field appears in the recognition result only when speaker diarization is enabled.

punctuation

string

The punctuation predicted after the word, if any.

transcribe

def transcribe(
    file_urls: List[str],
    *,
    model: str = "qwen-audio-3.1-asr-flash-filetrans",
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: float = 86400.0,
    submit_timeout: Optional[float] = None,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

Submit a task and wait synchronously for completion. The default model is qwen-audio-3.1-asr-flash-filetrans. Specify model explicitly to call another model.

jobs.create

def create(
    *,
    model: str,
    file_urls: List[str],
    parameters: Optional[Dict[str, Any]] = None,
    phrase_id: Optional[str] = None,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

Submit a task and return a Job containing task_id and status, without waiting for recognition to finish.

jobs.wait

def wait(
    job: Union[Job, str],
    *,
    poll_interval: float = 1.0,
    max_interval: float = 8.0,
    timeout: float = 86400.0,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

Pass a Job or task ID and wait synchronously for completion. Set the initial and maximum polling intervals with poll_interval and max_interval, and the total waiting time with timeout. All values are in seconds.

jobs.fetch

def fetch(
    task_id: str,
    *,
    timeout: Optional[float] = None,
    api_key: Optional[str] = None,
    workspace: Optional[str] = None,
) -> Job

Query the task status and results once by task ID, without waiting for completion.