Paraformer non-real-time speech recognition HTTP API

Submits a speech recognition task.

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription

POST

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.

The 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.
    }
}

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.

If your audio files are stored in OSS, the RESTful API supports temporary URLs that start with the oss:// prefix.

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_id corresponds to SDK's phrase_id field. phrase_id is v1-only hotword solution, unsupported by v2+ models. For models supporting this method, see Paraformer语音识别热词定制与管理.

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.

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 * 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_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:

• zh: Chinese
• en: English
• ja: Japanese
• yue: Cantonese
• ko: Korean
• de: German
• fr: French
• ru: Russian

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 speaker_id field to distinguish different speakers.

For an example of speaker_id, see Recognition result description.

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.

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.

Queries the status and result of a speech recognition task.

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

GET

Authorization: Bearer {api-key} // Replace {api-key} with your API key.

None.

task_id

string

-

Yes

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

task_id

string

The ID of the queried task.

task_status

string

The status of the queried task.

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.

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.

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