Alibaba Cloud Model Studio:Paraformer non-real-time speech recognition Python SDK

model

str

Yes

The model name for Paraformer audio and video file transcription. 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 audio files are stored in Alibaba Cloud OSS, the SDK does not support temporary URLs with the oss:// prefix.

vocabulary_id

str

No

The custom vocabulary ID. Supported for v2 series models; requires language configuration. Disabled by default. Custom Vocabularies.

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

Enables timestamp alignment. Disabled by default.

special_word_filter

str

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

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 Description of recognition results.

speaker_count

int

No

Reference speaker count. Integer from 2 to 100.

Takes effect only when diarization_enabled is true.

Determined automatically by default. Setting this parameter guides the algorithm but does not guarantee the exact count.

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 recognition results of the subtasks. Each item contains file_url, transcription_url, and subtask_status. For more information, 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 file to be recognized.

transcription_url

The URL corresponding to the audio recognition result.

The recognition result is saved as a JSON file. Download the file from the URL in transcription_url or read its content via an HTTP request. For JSON file content details, see Recognition result description.

usage

The metering information, including duration (the audio duration, in seconds).

code

The error code. Use with the message field. See Error codes.

message

The error message. Use with the code field. See Error codes.

subtask_status

The subtask status.

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

file_url

The URL of the audio file to be recognized.

transcription_url

The URL corresponding to the audio recognition result.

The recognition result is saved in a JSON file. Download the file from transcription_url or read its content via an HTTP request. For JSON content 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).

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 (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 (exponential-backoff polling, 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.