Skip to main content
HTTP API

Fun-ASR HTTP API for non-real-time speech recognition

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.

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:
  1. 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.
  2. 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}
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

ParameterTypeRequiredDescription
AuthorizationstringYesAuthentication 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-TypestringYesThe media type of the request body. Required only for the submit task interface. Fixed value: application/json.
X-DashScope-AsyncstringYesThe 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
# 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": "fun-asr",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'
ParameterTypeDescription
modelstring(Required) The model name. Supported values include the Fun-ASR model family. For details, see Supported models and regions.
inputobject(Required) The input parameter object.
input.file_urlsarray[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.
parametersobject(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_idstring(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.vocabularyobject(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_idarray[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_filterstring(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_enabledboolean(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_countinteger(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_hintsarray[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.
  • 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--************"
}
ParameterTypeDescription
request_idstringThe unique identifier of this call.
outputobjectThe data returned by the submit task interface.
output.task_idstringThe task ID. Pass this ID as the string in the Query task interface.
output.task_statusstringThe 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"
ParameterTypeDescription
task_idstring(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
  }
}
ParameterTypeDescription
outputobjectThe data returned by the query task interface.
output.task_idstringThe ID of the queried task.
output.task_statusstringThe 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_timestringThe time the task was submitted.
output.scheduled_timestringThe time the task was scheduled to run.
output.end_timestringThe time the task ended.
output.resultsarray[object]The list of subtask results, one for each audio file to recognize.
output.results.subtask_statusstringThe subtask status.
output.results.file_urlstringThe URL of the file processed by the file transcription task.
output.results.transcription_urlstringThe 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.codestringTip: Returned only when the subtask fails. The error code of the failed subtask.
output.results.messagestringTip: Returned only when the subtask fails. The error message of the failed subtask.
output.task_metricsobjectOverall execution statistics for the task.
output.task_metrics.TOTALintegerThe total number of subtasks.
output.task_metrics.SUCCEEDEDintegerThe number of successful subtasks.
output.task_metrics.FAILEDintegerThe 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.
{
    "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:
ParameterTypeDescription
audio_formatstringThe audio format of the source file.
channelsarray[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_rateintegerThe sampling rate (Hz) of the audio in the source file.
original_duration_in_millisecondsintegerThe original audio duration (ms) in the source file.
channel_idintegerThe track index of the transcription result, starting from 0.
content_durationintegerThe 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.
transcriptstringThe paragraph-level transcription result.
sentencesarrayThe sentence-level transcription result.
wordsarrayThe word-level transcription result.
begin_timeintegerThe start timestamp (ms).
end_timeintegerThe end timestamp (ms).
textstringThe transcription result.
speaker_idintegerThe 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.
punctuationstringThe punctuation predicted after the word, if any.