File transcription REST
This topic describes the parameters and interface details of the HTTP API for non-real-time speech recognition with Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR.
User guide: Non-real-time speech recognition. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.
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:
Sign in to QwenCloud and create an API key. To avoid security risks, export the API key as an environment variable instead of hard-coding it.
Submit task interface:
Submits a speech recognition task. This interface returns asynchronously, so poll the task status with the Query task interface.
The
If
Field descriptions:
Supported language codes by model:
Request headers:
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
The recognition result is saved as a JSON file.
Key parameters:
Request headers:
You can provide Base64-encoded audio as a Data URI in the format
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_idto indicate that the task was created successfully.
-
Step 2: Retrieve the result.
- The client uses the returned
task_idto poll the query interface repeatedly. - When the task finishes, the query interface returns the final recognition result.
- The client uses the returned
Prerequisites
Sign in to QwenCloud and create an API key. To avoid security risks, export the API key as an environment variable instead of hard-coding it.
To grant temporary access or restrict sensitive operations, use a temporary token.Temporary tokens expire in 60 seconds, reducing leakage risk. Replace the API key in your code with the temporary token.
Service endpoints
Submit task interface: POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription
Query task interface: GET https://dashscope-intl.aliyuncs.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 "<your_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.
- Basic call
- Inline hotwords
- Context
Request parameters
| Parameter | Type | Default value | Required | Description |
|---|---|---|---|---|
| model | string | - | Yes | The model name. Supported values include the Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR model families. For details, see Supported models and regions. |
| file_urls | array[string] | - | 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. |
| context | array(object) | - | No | A list of messages that provide optional conversation context to improve recognition accuracy. See context parameter details. |
| vocabulary_id | 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 | object | - | 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 configured together with precompiled hot words, only the instant hot words take effect. For usage details, see Instant hotwords. |
| channel_id | array[integer] | [0] | 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. |
| special_word_filter | string | - | 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. |
| diarization_enabled | boolean | false | 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. See Recognition result description. |
| speaker_count | integer | - | No | A reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive). Takes effect only when diarization_enabled is set to true. 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. |
| language_hints | array[string] | - | No | The language codes to recognize. If you cannot determine the language in advance, leave it unset and the model detects the language automatically. For Qwen-Audio-3.0-ASR-Flash-Filetrans models, you can set up to 4 values; any values beyond the first 4 are ignored. For Fun-ASR models, you can set only 1 value; if you set multiple, only the first takes effect. See Supported languages. |
Only
qwen-audio-3.0-asr-flash-filetrans supports inline hotwords (vocabulary parameter).Each audio track in
channel_id is billed separately. Example: [0, 1] on one file = two charges.When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out.
context parameter details
The context parameter is a list of messages that provide optional conversation context to improve recognition accuracy.
The SDK does not yet support this feature.
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.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.Sensitive word filter details
If special_word_filter is not set, the built-in filter replaces matched words with asterisks (*) of equal length.
If set, you can use these policies:
- Replace with
*: Replaces matched words with asterisks of the same length. - Filter out: Removes matched words from the result.
-
filter_with_signed- Type: object. Required: No.
- Matched words are replaced with asterisks of the same length.
- Example: "Help me test this piece of code" becomes "Help me **** this piece of code".
- Internal field:
word_list-- A string array of words to replace.
-
filter_with_empty- Type: object. Required: No.
- Matched words are removed from the result.
- Example: "Is the game about to start?" becomes "Is the game about to ?".
- Internal field:
word_list-- A string array of words to remove.
-
system_reserved_filter- Type: Boolean. Required: No. Default:
true. - Enables the system's preset sensitive word rules. When
true, words matching the QwenCloud sensitive word list are replaced with asterisks of the same length.
- Type: Boolean. Required: No. Default:
Supported languages
Supported language codes by model:
-
qwen-audio-3.0-asr-flash-filetrans, fun-asr, fun-asr-2025-11-07, fun-asr-mtl, fun-asr-mtl-2025-08-25:
zh: Chineseen: Englishja: Japaneseko: Koreanvi: Vietnameseid: Indonesianth: Thaims: Malaytl: Filipinoar: Arabicbg: Bulgarianhr: Croatiancs: Czechda: Danishnl: Dutchet: Estonianfi: Finnishel: Greekhi: Hindihu: Hungarianga: Irishlv: Latvianlt: Lithuanianmt: Maltesepl: Polishpt: Portuguesero: Romaniansk: Slovaksl: Sloveniansv: Swedish
-
fun-asr-2025-08-25:
zh: Chineseen: English
Response parameters
Click to view a response sample
Click to view a response sample
| Parameter | Type | Description |
|---|---|---|
| request_id | string | The unique identifier of this call. |
| task_status | string | The task status. Returns PENDING on successful submission. |
| task_id | string | The task ID. Use it with the Query task interface to check results. |
Query task interface
Basic information
| Item | Description |
|---|---|
| Description | Queries the execution status and result of a speech recognition task. Poll this interface until the task reaches a terminal state. |
| URL | https://dashscope-intl.aliyuncs.com/api/v1/tasks/\{task_id\} |
| Request method | GET |
| Request headers | See below |
| Message body | None |
Request parameters
Click to view a request sample
Click to view a request sample
| Parameter | Type | Default value | Required | Description |
|---|---|---|---|---|
| task_id | string | - | Yes | 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 parameters
Multi-subtask jobs: overall status shows
SUCCEEDED if any subtask succeeds. Check subtask_status to determine the result of a specific subtask.Click to view a response sample (success)
Click to view a response sample (success)
Click to view a response sample (partial failure)
Click to view a response sample (partial failure)
The
code field contains the error code, and the message field contains the error message. These fields appear only on errors.| Parameter | Type | Description |
|---|---|---|
| request_id | string | The unique identifier of this call. |
| task_id | string | The task ID. |
| task_status | string | The task status. |
| subtask_status | string | The subtask status. |
| file_url | string | The URL of the file processed by the file transcription task. |
| 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. |
| submit_time | string | The time the task was submitted. |
| scheduled_time | string | The time the task was scheduled to run. |
| end_time | string | The time the task ended. |
| task_metrics | object | Overall execution statistics for the task: TOTAL, SUCCEEDED (number of successful subtasks), and FAILED counts. |
| usage | object | Usage information. duration is the total duration in seconds. |
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
Click to view the recognition result example
The
speaker_id field appears only when speaker diarization is enabled. Other word entries are omitted for brevity.| 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_in_milliseconds | integer | The duration (ms) of content in the track that is identified as speech. |
| text | 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). |
| 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. |
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.
Fun-ASR-Flash (synchronous)
SDK calls are not supported for this feature. Use the HTTP API directly.
Basic information
| Item | Description |
|---|---|
| Description | Synchronously transcribes an audio file up to 5 minutes long. Optionally accepts conversation context to improve recognition of proper nouns. |
| URL | https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation |
| Request method | POST |
| Request headers | See below |
| Message body | See below |
Set
X-DashScope-SSE to enable to receive results incrementally over SSE, or to disable (or omit the header) to receive only the final result.Request parameters
- Non-streaming
- Streaming
- With context
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Set to fun-asr-flash-2026-06-15. |
| input.messages | array[object] | Yes | The message list. Contains the audio to transcribe and, optionally, conversation context to improve recognition accuracy. |
| input.messages[].role | string | Yes | user: the audio to transcribe (input_audio type), or a previous turn's transcription/word list for context (input_text type). assistant (optional, for context): an LLM response from a previous turn. |
| input.messages[].content[].type | string | Yes | input_audio (required, role must be user): the audio to transcribe. input_text (optional, for context, role must be user): a previous transcription result or domain-specific word list. text (optional, for context, role must be assistant): an LLM response from a previous turn. |
| input.messages[].content[].input_audio.data | string | Conditional | Required when type is input_audio. Either a publicly accessible audio file URL or a Base64 Data URI (data:{MIME_TYPE};base64,{DATA}, for example audio/wav or audio/mp3). |
| input.messages[].content[].text | string | Conditional | Required when type is input_text or text. Text length is counted per character; the combined length of all text fields in a turn must not exceed 400 characters, with excess truncated from the end. |
| parameters.format | string | Yes | The audio format, for example wav, mp3, or opus. |
| parameters.sample_rate | string | No | The audio sample rate in Hz, for example 16000. |
Context messages (
input_text and text types) are limited to 5 each. When exceeded, only the 5 most recent are retained. The order of messages matters: each user context message must precede its corresponding assistant message, and the user message with input_audio must always be last in input.messages.Base64
You can provide Base64-encoded audio as a Data URI in the format data:{MIME_TYPE};base64,{DATA}:
{MIME_TYPE}: MIME type, which varies by audio format. For example: WAV usesaudio/wav, MP3 usesaudio/mpeg.{DATA}: The Base64-encoded string of the audio file.
data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
- Python
- Java
Response parameters
- Non-streaming
- Streaming
| Parameter | Type | Description |
|---|---|---|
| request_id | string | The unique identifier of this request. |
| output.text | string | The accumulated full transcription text up to this point. |
| output.sentence.sentence_id | integer | The sentence number, starting from 1. |
| output.sentence.sentence_end | boolean | Whether recognition for this sentence is complete. |
| output.sentence.begin_time | integer | The sentence start time (ms). |
| output.sentence.end_time | integer | The sentence end time (ms). Returned only when sentence_end is true. |
| output.sentence.text | string | The transcription text for the current sentence. |
| output.sentence.channel_id | integer | The audio channel number, starting from 0. |
| output.sentence.words | array | The word-level timestamp list. |
| output.sentence.words[].text | string | The word text. |
| output.sentence.words[].begin_time | integer | The word start time (ms). |
| output.sentence.words[].end_time | integer | The word end time (ms). |
| output.sentence.words[].punctuation | string | The punctuation mark after the word, if any. |
| output.sentence.words[].fixed | boolean | Whether the word is finalized. false means the timestamp may still change in later events. |
| usage.duration | integer | The duration of processed audio, in seconds. Returned only when sentence_end is true. |
For each SSE event, parse the JSON in the
data field, and check output.sentence.sentence_end to determine whether the sentence is final. usage is included only in sentence-end events.