Paraformer non-real-time speech recognition Python SDK

model

str

Yes

The name of the Paraformer model used for audio and video file transcription. See Supported models.

file_urls

list[str]

Yes

A list of URLs for audio and video file transcription. The HTTP and HTTPS protocols are supported. A single request supports only 1 URL.

If the recorded files are stored in Alibaba Cloud OSS, the SDK does not support temporary URLs prefixed with oss://.

vocabulary_id

str

No

The latest hot word ID. Supported by the latest v2 series models with language information configured. The hot words corresponding to this hot word ID take effect in this speech recognition. Disabled by default. For usage, see Custom hot words.

channel_id

list[int]

[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

bool

False

No

Filters filler words. Disabled by default.

timestamp_alignment_enabled

bool

False

No

Whether to enable timestamp alignment. Disabled by default.

special_word_filter

str

No

Specifies the sensitive words to be processed 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

list[str]

["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

bool

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

int

No

Reference speaker count. The value is an integer from 2 to 100 (inclusive).

Takes effect after speaker diarization is enabled (diarization_enabled set to true).

By default, the number of speakers is determined automatically. If this parameter is configured, it only guides the algorithm to output the specified count as closely as possible, without guaranteeing that this count will be output.

request_id

The ID generated by the system to identify this call.

task_id

The task ID.

status

The task status.

The four statuses are PENDING, RUNNING, SUCCEEDED, and FAILED.

When a task contains multiple subtasks, if any subtask succeeds, the entire task status is marked as SUCCEEDED. Check the subtask_status field to determine the result of each specific subtask.

results

The subtask recognition results. Each item contains file_url, transcription_url, and subtask_status. See Subtask recognition results.

subtask_status

The subtask status.

The four statuses are PENDING, RUNNING, SUCCEEDED, and FAILED.

file_url

The URL of the audio to be recognized.

transcription_url

The URL corresponding to the audio recognition result.

The recognition result is saved as a JSON file. You can download the file from the link corresponding to transcription_url or read the content of the file directly through an HTTP request. For the JSON file content, see Recognition result description.

usage

Metering information, including duration (audio duration in seconds).

code

The error code. Use it together with the message field and refer to Error codes to troubleshoot.

message

The error message. Use it together with the code field and refer to Error codes to troubleshoot.

subtask_status

The subtask status.

The four statuses are PENDING, RUNNING, SUCCEEDED, and FAILED.

file_url

The URL of the audio to be recognized.

transcription_url

The URL corresponding to the audio recognition result.

The recognition result is saved in JSON format in a JSON file. You can download the file from the link corresponding to transcription_url or read the content of the file directly through an HTTP request. For the JSON file content, 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).

transcribe

def transcribe(self,
               file_urls: List[str],
               *,
               model: str = "paraformer-v2",
               parameters: Dict = None,
               phrase_id: str = None,
               timeout: float = ...,
               ...) -> Job

Submits a recorded file recognition task and blocks the current thread until the task completes (the task status is SUCCEEDED or FAILED).

This method returns a Job. Read the transcription results from job.results (each item contains transcription_url).

jobs.create

def create(self,
           *,
           model: str,
           file_urls: List[str],
           parameters: Dict = None,
           phrase_id: str = None,
           ...) -> Job

Asynchronously submits a speech recognition task.

This method returns a Job (job.task_id/job.status).

jobs.wait

def wait(self,
         task: Union[str, Job],
         poll_interval: float = 1,
         timeout: float = 86400,
         ...) -> Job

Blocks the current thread until the asynchronous task completes (polling with exponential backoff, with a default total budget of 24 hours).

This method returns the final-state Job.

jobs.fetch

def fetch(self,
          task_id: str,
          ...) -> Job

Asynchronously queries the current task execution result.

This method returns a Job.