The parameters and API details for Paraformer audio file recognition RESTful API.
Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Replace {WorkspaceId} with your actual Workspace ID. The existing domain remains fully functional.
User guide: Non-real-time speech recognition
The service provides a task submission interface and a task query interface. Typically, you call the task submission interface to upload a recognition task and then repeatedly call the task query interface until the task is complete.
Prerequisites
You have activated the service and Obtain an API key. Please Configure API key as an environment variable instead of hardcoding it in your code to prevent security risks caused by code leakage.
When you need to provide temporary access to third-party applications or users, or when you want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using temporary authentication tokens.
Compared with long-term API Keys, temporary authentication tokens have a short validity period (60 seconds) and higher security, making them suitable for temporary call scenarios and effectively reducing the risk of API Key leakage.
Usage: In your code, replace the API Key originally used for authentication with the obtained temporary authentication token.
Task submission interface
Basic information
|
API endpoint description |
Submits a speech recognition task. |
|
URL |
|
|
Request method |
POST |
|
Request headers |
|
|
Message body |
The following code shows a message body that contains all request parameters. You can omit optional fields as needed. |
Request parameters
|
Parameter |
Type |
Default value |
Required |
Description |
|
model |
string |
- |
Yes |
The name of the Paraformer model that is used for audio and video file transcription. For more information, see models. |
|
file_urls |
array[string] |
- |
Yes |
List of URLs for audio and video file transcription (HTTP/HTTPS). A single request supports only 1 URL. Important
If a URL contains spaces, Chinese characters, or other special characters, URL-encode it before use (for example, replace spaces with If your audio files are stored in OSS, the RESTful API supports temporary URLs that start with the oss:// prefix. Important
|
|
vocabulary_id |
string |
- |
No |
Custom vocabulary ID. Supported by v2+ models with language configurations. Hotwords for this ID apply to current speech recognition. Disabled by default. For usage, see Custom hotwords. |
|
resource_id |
string |
- |
No |
The hotword ID. The hotword information that corresponds to this hotword ID takes effect in this speech recognition task. This feature is disabled by default. Note: |
|
resource_type |
string |
- |
No |
Must be set to "asr_phrase". This parameter must be used together with "resource_id". |
|
channel_id |
array[integer] |
[0] |
No |
Specifies the audio track indexes to recognize in a multi-track audio file. Indexes start from 0. For example, [0] means recognizing the first track, and [0, 1] means recognizing both the first and second tracks simultaneously. If this parameter is omitted, only the first track is processed by default. Important Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges. |
|
disfluency_removal_enabled |
boolean |
false |
No |
Filters filler words. Disabled by default. |
|
timestamp_alignment_enabled |
boolean |
false |
No |
Enables timestamp alignment feature. Disabled by default. |
|
special_word_filter |
string |
- |
No |
Specifies sensitive words to process during speech recognition and supports setting different processing methods for different sensitive words. If this parameter is not provided, the system uses the built-in sensitive word filtering logic, and words matching the Alibaba Cloud Model Studio sensitive word list in the recognition results will be replaced with If this parameter is provided, the following sensitive word processing strategies can be implemented:
The value of this parameter should be a JSON string with the following structure: JSON field descriptions:
|
|
language_hints |
array[string] |
["zh", "en"] |
No |
Specifies the language codes of the speech to be recognized. This parameter is only applicable to the paraformer-v2 model. Supported language codes:
|
|
diarization_enabled |
boolean |
false |
No |
Automatic speaker diarization. Disabled by default. Only applicable to mono audio. Multi-channel audio does not support speaker diarization. When this feature is enabled, the recognition results will include a Note If speaker diarization is enabled, it is recommended that the audio duration does not exceed 2 hours, otherwise recognition may fail or time out. For an example of |
|
speaker_count |
integer |
- |
No |
Reference value for speaker count (integer from 2 to 100, inclusive). Takes effect when diarization_enabled is true. Speaker count is automatically determined by default. Configuring this parameter assists the algorithm in targeting the specified count but does not guarantee exact output. |
Response parameters
|
Parameter |
Type |
Description |
|
task_status |
string |
The task status. |
|
task_id |
string |
The task ID. This ID is passed as a request parameter in the task query interface. |
Task query interface
Basic information
|
API endpoint description |
Queries the status and result of a speech recognition task. |
|
URL |
|
|
Request method |
GET |
|
Request headers |
|
|
Message body |
None. |
Request parameters
|
Parameter |
Type |
Default value |
Required |
Description |
|
task_id |
string |
- |
Yes |
Task ID required for query. Returned by the task submission interface. |
Response parameters
|
Parameter |
Type |
Description |
|
task_id |
string |
The ID of the queried task. |
|
task_status |
string |
The status of the queried task. Note
For tasks with multiple subtasks, task_status shows |
|
subtask_status |
string |
The subtask status. |
|
file_url |
string |
The URL of the file that is processed in the file transcription task. |
|
transcription_url |
string |
Link to obtain recognition result (valid 24 hours). After expiration, task queries and result downloads fail. Recognition result is saved as JSON. Download from this link or read directly via HTTP request. For JSON field details, see Recognition result description. |
Recognition result description
The recognition result is saved as a JSON file.
The key parameters are as follows:
Parameter | Type | Description |
audio_format | string | The audio format of the source file. |
channels | array[integer] | The audio track index information of the source file. Returns [0] for mono audio, [0, 1] for dual-track audio, and so on. |
original_sampling_rate | integer | The sampling rate (Hz) of the audio in the source file. |
original_duration | integer | The original audio duration (ms) of the source file. |
channel_id | integer | The audio track index of the transcription result, starting from 0. |
content_duration | integer | The duration (ms) of content identified as speech in the audio track. Important The Paraformer speech recognition model service only transcribes and meters content identified as speech in the audio track, and bills accordingly. Non-speech content is neither metered nor billed. Typically, the speech content duration is shorter than the original audio duration. Since the determination of whether speech content exists is made by an AI model, there may be some deviation from the actual situation. |
transcript | string | The paragraph-level speech transcription result. |
sentences | array | The sentence-level speech transcription result. |
words | array | The word-level speech transcription result. |
begin_time | integer | The start timestamp (ms). |
end_time | integer | The end timestamp (ms). |
text | string | The speech transcription result. |
speaker_id | integer | The index of the current speaker, starting from 0, used to distinguish different speakers. This field is only displayed in the recognition results when speaker diarization is enabled. |
punctuation | string | The predicted punctuation after the word (if any). |
Other interfaces: Batch query task status / Cancel task
For details, see Manage asynchronous tasks: Supports batch querying of recorded speech recognition tasks submitted within the last 24 hours, and also supports canceling tasks in PENDING (queued) state.
Complete example
Use built-in HTTP libraries to implement task submission and query requests. First submit the recognition task, and then repeatedly query until complete.
The following code provides an example in Python:
import requests
import json
import time
api_key = "your-dashscope-api-key" # Replace this with your API key.
file_urls = [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
]
language_hints = ["zh", "en"]
# Submit file transcription task with list of file URLs to transcribe.
def submit_task(apikey, file_urls) -> str:
headers = {
"Authorization": f"Bearer {apikey}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
data = {
"model": "paraformer-v2",
"input": {"file_urls": file_urls},
"parameters": {
"channel_id": [0],
"language_hints": language_hints
},
}
# The URL of the recorded file transcription service.
service_url = (
"https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"
)
response = requests.post(
service_url, headers=headers, data=json.dumps(data)
)
# Print the response content.
if response.status_code == 200:
return response.json()["output"]["task_id"]
else:
print("task failed!")
print(response.json())
return None
# Recursively query the task status until the task is successful.
def wait_for_complete(task_id):
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
pending = True
while pending:
# The URL of the task status query service.
service_url = f"https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}"
response = requests.get(
service_url, headers=headers
)
if response.status_code == 200:
status = response.json()['output']['task_status']
if status == 'SUCCEEDED':
print("task succeeded!")
pending = False
return response.json()['output']['results']
elif status == 'RUNNING' or status == 'PENDING':
pass
else:
print("task failed!")
pending = False
else:
print("query failed!")
pending = False
print(response.json())
time.sleep(0.1)
task_id = submit_task(apikey=api_key, file_urls=file_urls)
print("task_id: ", task_id)
result = wait_for_complete(task_id)
print("transcription result: ", result)Error codes
If you encounter errors, see Error codes for troubleshooting.
If the issue persists, join the developer community to report the issue and provide the Request ID for further investigation.
When a task contains multiple subtasks, as long as any subtask succeeds, the overall task status is marked as SUCCEEDED. You need to check the subtask_status field to determine the result of each subtask.
Error response example:
{
"task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2024-12-16 16:30:59.170",
"scheduled_time": "2024-12-16 16:30:59.204",
"end_time": "2024-12-16 16:31:02.375",
"results": [
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_exaple_1.wav",
"code": "InvalidFile.DownloadFailed",
"message": "The audio file cannot be downloaded.",
"subtask_status": "FAILED"
}
],
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 0,
"FAILED": 1
}
}More examples
For more examples, see our GitHub repository.
FAQ
Features
Q: Does it support Base64-encoded audio?
No. Base64-encoded audio is not supported. Only audio accessible via publicly accessible URLs is supported. Binary streams and direct local file recognition are not supported.
Q: How to provide audio files as publicly accessible URLs?
Generally, follow these steps (this provides a general approach; specifics vary by storage product. We recommend uploading audio to Alibaba Cloud OSS):
When using the SDK, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are not supported.
When using the RESTful API, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are supported:
The temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in a production environment.
The API for obtaining an upload credential is limited to 100 QPS and does not support scaling out. Do not use it in production environments, high-concurrency scenarios, or stress testing scenarios.
For production environments, use a stable storage service such as OSS to ensure long-term file availability and avoid rate limiting issues.
Q: How long does it take to get recognition results?
After submission, the task enters a queued (PENDING) state. The queue time depends on the queue length and file duration and cannot be precisely estimated, but typically completes within a few minutes. Please wait patiently. Longer audio files require more processing time.
Troubleshooting
If you encounter an error, refer to the information in Error codes.
Q: What should I do if the recognition results are not synchronized with the audio playback?
Set timestamp_alignment_enabled request parameter to true. This synchronizes recognition results with audio playback.
Q: What should I do if I get an InvalidFile.DownloadFailed error after submitting a task?
Check whether the file URL contains spaces, Chinese characters, or other special characters. If the file name includes spaces (for example, "Meeting Recording Q1 2024.mp4"), URL-encode the file name by replacing spaces with %20 before passing it to the file_urls parameter.
Q: What do I do if the temporary public access URL of an OSS audio file is inaccessible?
Set X-DashScope-OssResourceResolve to enable in headers.
Not recommended.
The Java SDK and the Python SDK don't support configuring headers.
Q: Unable to get results after continuous polling?
This may be due to rate limiting. Please wait patiently. If you need capacity expansion, join the developer community to apply.
Q: Why is there no recognition result (unable to recognize speech)?
Check whether the audio meets the requirements (format, sampling rate).
If you are using the
paraformer-v2model, check whether thelanguage_hintssetting is correct.If none of the above resolves the issue, you can customize hot words to improve the recognition of specific words.
More questions
For more questions, see the FAQ on GitHub.