Qwen-Audio-ASR-Filetrans HTTP API for non-real-time speech recognition

For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.

How it works

Unlike synchronous DashScope calls, which return the result immediately in a single request, asynchronous calls are designed for long audio files or time-consuming tasks. This mode uses a two-step submit-and-poll flow that avoids request timeouts caused by long waits:

Step 1: Submit the task.
- The client sends an asynchronous processing request.
- After validating the request, the server does not run the task immediately. Instead, it returns a unique task_id to indicate that the task was created successfully.
Step 2: Retrieve the result.
- The client uses the returned task_id to poll the query interface repeatedly.
- When the task finishes, the query interface returns the final recognition result.

Service endpoints

The following uses the Singapore (ap-southeast-1) endpoint. For another region, replace ap-southeast-1 with the region ID and use an API key from that region. See Regions and endpoints. Submit task interface: POST https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/audio/asr/transcription Query task interface: GET https://ap-southeast-1.maas.qwencloudapi.com/api/v1/tasks/{task_id}

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format `Bearer $DASHSCOPE_API_KEY`. Replace "`$DASHSCOPE_API_KEY`" with your actual API key. Required for both the submit task interface and the query task interface.
Content-Type	string	Yes	The media type of the request body. Required only for the submit task interface. Fixed value: `application/json`.
X-DashScope-Async	string	Yes	The asynchronous task flag. Required only for the submit task interface. Fixed value: `enable`. Do not omit it, or the task cannot be submitted.

Submit task interface

Submits a speech recognition task. This interface returns asynchronously, so poll the task status with the Query task interface.

If a dedicated deployment returns current user api does not support asynchronous calls, set X-DashScope-Async to disable and use a synchronous request.

Request body

Basic call
Inline hotwords
Context

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --location 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

Use inline hotwords in the following format:

{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

Use context in the following format:

{
    "model": "qwen-audio-3.1-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ],
        "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?"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

Parameter	Type	Description
model	string	(Required) The model name. Supported values include the Qwen-Audio-ASR-Filetrans model family. For details, see Supported models and regions.
input	object	(Required) The input parameter object.
input.file_urls	array[string]	(Required) 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. Tip: - A temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in production. The upload credential interface is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or load-testing scenarios. For production, use stable storage such as Alibaba Cloud OSS to keep files available long-term and avoid rate limiting. If an audio file URL set to an OSS temporary public URL is unreachable, set `X-DashScope-OssResourceResolve` to `enable` in the request header (not recommended). The SDK does not support configuring request headers.
input.context	array(object)	(Optional) A list of messages that provide optional conversation context to improve recognition accuracy. Tip: The SDK does not yet support this feature. Tip: Context enhancement improves the recognition accuracy of domain-specific terms. For usage, see Context enhancement. Constraints: Context messages of the `input_text` and `text` types are each limited to 5 messages. If you exceed this limit, only the most recent 5 are kept. The total text length per context turn (the combined length of the `text` fields for `user` and `assistant`) must not exceed 400 characters (counted per character, each character counts as 1). Any excess is truncated from the end. Tip: When you include context, the message order in `messages` matters: context messages must be arranged by conversation turn. Within each turn, the `user` message (`input_text` type) must come before the corresponding `assistant` message (`text` type). A `user` message that contains `input_audio` must be placed last in the `messages` array.
input.context.role	string	(Required) The message role. Valid values: `user`: recognition results from previous turns or a domain-specific word list. `assistant`: the large language model's replies from previous turns.
input.context.content	array(object)	(Required) The list of message content items.
input.context.content.type	string	(Required) The content type. Valid values: `input_text` (optional, context): recognition results of the user's speech from previous turns, or a domain-specific word list (role is user). You must also pass the `text` field. `text` (optional, context): the large language model's replies from previous turns (role is assistant). You must also pass the `text` field.
input.context.content.text	string	(Conditionally required) When `type` is `input_text`, enter the recognition results of the user's speech from previous turns or a domain-specific word list. When `type` is `text`, enter the large language model's replies from previous turns. Text is counted per character, and each character counts as 1. The combined length of the `text` fields across all messages in a context turn must not exceed 400 characters. Any excess is truncated from the end.
parameters	object	(Required) The request parameter object. Always include `parameters`, using an empty object `{}` if no options are needed. Omitting this field causes the submitted transcription task to fail.
parameters.keep_dialect	boolean	(Optional) Supported only by `qwen-audio-3.1-asr-flash-filetrans`. Specifies whether to preserve dialect expressions. Default: `false`. Set to `false` to transcribe dialect speech as standard Mandarin text, or `true` to preserve dialect expressions.
parameters.vocabulary_id	string	(Optional) 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	object	(Optional) 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. Tip: Only `qwen-audio-3.1-asr-flash-filetrans` and `qwen-audio-3.0-asr-flash-filetrans` support inline hotwords.
parameters.channel_id	array[integer]	(Optional) 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. Tip: Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges. Default value: [0].
parameters.special_word_filter	string	(Optional) Words to replace or remove. The parameter is a JSON string with these fields: `filter_with_signed.word_list`: A string array of words to replace with an equal number of `` characters. `filter_with_empty.word_list`: A string array of words to remove from the result. `system_reserved_filter`: A boolean, default `true`, that controls whether to also use the built-in word list. Custom rules still apply when it is `false`. If this parameter is omitted, matches in the built-in word list are replaced with an equal number of `` characters. For an example, see Sensitive word filtering.
parameters.diarization_enabled	boolean	(Optional) 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. Note: When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out. For an example of `speaker_id`, see Recognition result description. Default value: false.
parameters.speaker_count	integer	(Optional) Tip: Takes effect only when speaker diarization is enabled (`diarization_enabled` is set to `true`). 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	array[string]	(Optional) 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; any values beyond the first 4 are ignored. zh: Chinese en: English ja: Japanese ko: Korean vi: Vietnamese th: Thai id: Indonesian ms: Malay tl: Filipino hi: Hindi ar: Arabic fr: French de: German es: Spanish pt: Portuguese ru: Russian it: Italian nl: Dutch sv: Swedish da: Danish fi: Finnish no: Norwegian el: Greek pl: Polish cs: Czech hu: Hungarian ro: Romanian bg: Bulgarian hr: Croatian sk: Slovak

Response body

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

Parameter	Type	Description
request_id	string	The unique identifier of this call.
output	object	The data returned by the submit task interface.
output.task_id	string	The task ID. Pass this ID as the string in the Query task interface.
output.task_status	string	The task status. Returns `PENDING` on successful submission.

Query task interface

Queries the execution status and result of a speech recognition task. Poll this interface until the task reaches a terminal state.

Request body

# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
curl --location 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter	Type	Description
task_id	string	(Required) Tip: This parameter is a URL path parameter. There is no request body. To query a task, specify its ID. This ID is the `task_id` returned when the Submit task interface is called.

Response body

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

Parameter	Type	Description
output	object	The data returned by the query task interface.
output.task_id	string	The ID of the queried task.
output.task_status	string	The status of the queried task. Note: 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 a specific subtask.
output.submit_time	string	The time the task was submitted.
output.scheduled_time	string	The time the task was scheduled to run.
output.end_time	string	The time the task ended.
output.results	array[object]	The list of subtask results, one for each audio file to recognize.
output.results.subtask_status	string	The subtask status.
output.results.file_url	string	The URL of the file processed by the file transcription task.
output.results.transcription_url	string	The link to the recognition result. This link is valid for 24 hours. After it expires, you cannot query the task or download the result through the URL returned by a previous query. The recognition result is saved as a JSON file. You can download the file through the link above or read its content directly with an HTTP request. For the meaning of each field in the JSON data, see Recognition result description.
output.results.code	string	Tip: Returned only when the subtask fails. The error code of the failed subtask.
output.results.message	string	Tip: Returned only when the subtask fails. The error message of the failed subtask.
output.task_metrics	object	Overall execution statistics for the task.
output.task_metrics.TOTAL	integer	The total number of subtasks.
output.task_metrics.SUCCEEDED	integer	The number of successful subtasks.
output.task_metrics.FAILED	integer	The number of failed subtasks.

Other interfaces: batch-query task status / cancel a task

For details, see Manage asynchronous tasks: you can batch-query non-real-time speech recognition tasks submitted within the last 24 hours, and cancel tasks in the PENDING (queued) state.

Recognition result description

The recognition result is saved as a JSON file.

Click to view the recognition result example

{
    "file_url":"{YOUR_AUDIO_URL}",
    "properties":{
        "audio_format":"pcm_s16le",
        "channels":[
            0
        ],
        "original_sampling_rate":16000,
        "original_duration_in_milliseconds":3834
    },
    "transcripts":[
        {
            "channel_id":0,
            "content_duration_in_milliseconds":3720,
            "text":"Hello world, this is Alibaba Speech Lab.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is Alibaba Speech Lab.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}

The following parameters are worth noting:

Parameter	Type	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.

Billing scope of content duration

The content_duration billing description above applies to qwen-audio-3.0-asr-flash-filetrans. qwen-audio-3.1-asr-flash-filetrans is billed by token usage. The downloaded result still includes speech-content duration, but its presence does not imply duration billing for every model.

​How it works

​Service endpoints

​Request headers

​Submit task interface

​Request body

​Response body

​Query task interface

​Request body

​Response body

​Other interfaces: batch-query task status / cancel a task

​Recognition result description

​Billing scope of content duration

How it works

Service endpoints

Request headers

Submit task interface

Request body

Response body

Query task interface

Request body

Response body

Other interfaces: batch-query task status / cancel a task

Recognition result description

Billing scope of content duration