Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Non-real-time speech recognition (Paraformer)

Paraformer non-real-time speech recognition HTTP API

The parameters and API details for Paraformer non-real-time speech recognition HTTP 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.
This document applies only to the China (Beijing) region. To use the model, you must use an API key from the China (Beijing) region.
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 descriptionSubmits a speech recognition task.
URL
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Request methodPOST
Request headers
Authorization: Bearer {api-key} // Replace {api-key} with your API key.
Content-Type: application/json
X-DashScope-Async: enable // Do not omit this request header. Otherwise, the task cannot be submitted.
Message bodyThe following code shows a message body that contains all request parameters. You can omit optional fields as needed.
{
    "model":"paraformer-v2", // The model name. This parameter is required.
    "input":{
        "file_urls":[
            "{YOUR_AUDIO_URL}"
        ] // The file to be recognized. This parameter is required.
    },
    "parameters":{
        "channel_id":[
            0
        ], // The audio track index. This parameter is optional.
        "disfluency_removal_enabled":false, // The switch for filtering filler words. This parameter is optional.
        "timestamp_alignment_enabled": false, // Specifies whether to enable the timestamp calibration feature. This parameter is optional.
        "special_word_filter": "xxx", // The sensitive words. This parameter is optional.
        "language_hints":[ // This parameter is applicable only to the paraformer-v2 model. Do not use this field for other models.
            "zh",
            "en"
        ],
        "diarization_enabled":false, // Specifies whether to enable automatic speaker diarization. This parameter is optional.
        "speaker_count": 2 // The reference number of speakers. This parameter is optional.
    }
}

Request parameters

cURL example for task submission interface:
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.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":"paraformer-v2","input":{"file_urls":["{YOUR_AUDIO_URL}"]},"parameters":{"channel_id":[0]}}'
ParameterTypeDefault valueRequiredDescription
modelstring
YesThe name of the Paraformer model that is used for audio and video file transcription. For more information, see models.
file_urlsarray[string]
YesList of URLs for audio and video file transcription (HTTP/HTTPS). A single request supports only 1 URL.
If a URL contains spaces, Chinese characters, or other special characters, URL-encode it before use (for example, replace spaces with %20). Otherwise, the download may fail with an InvalidFile.DownloadFailed error.
If your audio files are stored in OSS, the RESTful API supports temporary URLs that start with the oss:// prefix.
  • 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.
vocabulary_idstring
NoCustom 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.
channel_idarray[integer][0]NoSpecifies 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.
Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges.
disfluency_removal_enabledbooleanfalseNoFilters filler words. Disabled by default.
timestamp_alignment_enabledbooleanfalseNoEnables timestamp alignment feature. Disabled by default.
special_word_filterstring
NoSpecifies 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 * of equal length.If this parameter is provided, the following sensitive word processing strategies can be implemented:
  • Replace with *: Replace matching sensitive words with * of equal length.
  • Filter directly: Completely remove matching sensitive words from the recognition results.
The value of this parameter should be a JSON string with the following structure:
{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}
JSON field descriptions:
  • filter_with_signed
    • Type: Object.
    • Required: No.
    • Description: Configures the list of sensitive words to be replaced with *. Matching words in the recognition results will be replaced with * of equal length.
    • Example: Using the JSON above, the speech recognition result for "Help me test this code" would be "Help me **** this code".
    • Internal fields:
      • word_list: An array of strings listing the sensitive words to be replaced.
  • filter_with_empty
    • Type: Object.
    • Required: No.
    • Description: Configures the list of sensitive words to be removed (filtered) from the recognition results. Matching words will be completely deleted.
    • Example: Using the JSON above, the speech recognition result for "The game is about to start, right?" would be "The game is about to, right?".
    • Internal fields:
      • word_list: An array of strings listing the sensitive words to be completely removed (filtered).
  • system_reserved_filter
    • Type: Boolean.
    • Required: No.
    • Default: true.
    • Description: Whether to enable the system's built-in sensitive word rules. When set to true, the system's built-in sensitive word filtering logic is also enabled, and words matching the Alibaba Cloud Model Studio sensitive word list in the recognition results will be replaced with * of equal length.
language_hintsarray[string]["zh", "en"]NoSpecifies the language codes of the speech to be recognized.This parameter is only applicable to the paraformer-v2 model.Supported language codes:
  • zh: Chinese
  • en: English
  • ja: Japanese
  • yue: Cantonese
  • ko: Korean
  • de: German
  • fr: French
  • ru: Russian
diarization_enabledbooleanfalseNoAutomatic 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 speaker_id field to distinguish different speakers.
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_id, see Recognition result description.
speaker_countinteger
NoReference 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 

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

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 descriptionQueries the status and result of a speech recognition task.
URL
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Request methodGET
Request headers
Authorization: Bearer {api-key} // Replace {api-key} with your API key.
Message bodyNone.

Request parameters 

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter

Type

Default value

Required

Description

task_id

string

-

Yes

Task ID required for query. Returned by the task submission interface.

Response parameters

If a task contains multiple subtasks, the status of the entire task is marked as SUCCEEDED if any subtask succeeds. You must check the subtask_status field to determine the result of each subtask.
  • Normal example
  • Exception example
{
  "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

task_id

string

The ID of the queried task.

task_status

string

The status of the queried task.

For tasks with multiple subtasks, task_status shows SUCCEEDED if any subtask succeeds. Check the subtask_status field to determine individual subtask results.

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. 
{
    "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 the Alibaba speech laboratory.",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, this is the Alibaba speech laboratory.",
                    "sentence_id":1,
                    "speaker_id":0, //This field is only displayed 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 omitted here
                    ]
                }
            ]
        }
    ]
}
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.

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).

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 = [
    "{YOUR_AUDIO_URL}",
]
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": "{YOUR_AUDIO_URL}",
            "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):
For example:
  • Object Storage Service (recommended):
    • Use a cloud provider's object storage service (such as Alibaba Cloud OSS) to upload audio files to a bucket and set them to public access.
    • Advantages: High availability, CDN acceleration support, easy management.
  • Web server:
    • Place audio files on a web server that supports HTTP/HTTPS access (such as Nginx or Apache).
    • Advantages: Suitable for small projects or local testing.
  • Content Delivery Network (CDN):
    • Host audio files on a CDN and access them through the CDN-provided URL.
    • Advantages: Accelerated file delivery, suitable for high-concurrency scenarios.
Upload audio files based on your chosen storage/hosting method, for example:
  • Object Storage Service:
    • Log in to the cloud provider's console and create a bucket.
    • Upload audio files and set file permissions to "public read" or generate temporary access links.
  • Web server:
    • Place audio files in the server's designated directory (such as /var/www/html/audio/).
    • Ensure files are accessible via HTTP/HTTPS.
For example:
  • Object Storage Service:
    • After uploading, the system automatically generates a public access URL (typically in the format https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
    • If you need a more user-friendly domain, you can bind a custom domain and enable HTTPS.
  • Web server:
    • The file access URL is typically the server address plus the file path (such as https://your-domain.com/audio/file.mp3).
  • CDN:
    • After configuring CDN acceleration, use the CDN-provided URL (such as https://cdn.your-domain.com/audio/file.mp3).
In a public network environment, ensure the generated URL is accessible, for example:
  • Open the URL in a browser and check whether the audio file can be played.
  • Use tools (such as curl or Postman) to verify whether the URL returns a correct HTTP response (status code 200).
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 Paraformer non-real-time speech recognition 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-v2 model, check whether the language_hints setting 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.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
API Usage
Text Generation
Image Generation
  • FAQ
Video Generation
Audio
Real-time Multimodal
Realtime API
Text Embedding
More Models
Toolkit/Framework
Model Production
File Management
More