This topic describes the parameters and interface details of the HTTP API for non-real-time speech recognition with Fun-ASR.
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:
The following uses the Singapore (ap-southeast-1) endpoint. For another region, replace
Submits a speech recognition task. This interface returns asynchronously, so poll the task status with the Query task interface.
Queries the execution status and result of a speech recognition task. Poll this interface until the task reaches a terminal state.
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.
The following parameters are worth noting:
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
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}
When you submit a task with the new domain (
https://ap-southeast-1.maas.qwencloudapi.com), the request body must include the parameters object. Even if you don't need to set any parameters, pass an empty object {}. Otherwise, the task is submitted successfully but recognition fails.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.
Request body
- Basic call
- Inline hotwords
| Parameter | Type | Description |
|---|---|---|
| model | string | (Required) The model name. Supported values include the Fun-ASR 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.
|
| parameters | object | (Optional) The request parameter object. Tip: When you use the new domain (https://ap-southeast-1.maas.qwencloudapi.com), parameters is required. Even if you don't need to set any parameters, pass an empty object {}. If you omit this field, the task is submitted successfully, but the query task interface returns a recognition failure. |
| 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. |
| 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:
* 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 only 1 value; if you set multiple, only the first takes effect.
|
Response body
| 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
| 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
| 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
Click to view the recognition result example
| 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. |