Alibaba Cloud Model Studio:Paraformer recording file recognition Python SDK

Input requirements

The service does not accept local files or base64-encoded audio. Provide publicly accessible file URLs (HTTP or HTTPS).

Specify URLs using the file_urls parameter. A single request supports up to 100 URLs.

Supported formats

aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv

Audio constraints

To process larger files, see Preprocess video files to improve transcription efficiency.

Recognizable languages

• paraformer-v2: Chinese (Mandarin and 18 dialects), English, Japanese, Korean, German, French, Russian

• paraformer-8k-v2: Chinese only

Submit and wait for results

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# To set the API key directly instead of using an environment variable:
# import dashscope
# dashscope.api_key = "<your-api-key>"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=[
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav',
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav'
    ],
    language_hints=['zh', 'en']  # paraformer-v2 only
)

transcribe_response = Transcription.wait(task=task_response.output.task_id)
if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('Transcription done!')

Submit and poll for results

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json

# To set the API key directly instead of using an environment variable:
# import dashscope
# dashscope.api_key = "<your-api-key>"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=[
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav',
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav'
    ],
    language_hints=['zh', 'en']  # paraformer-v2 only
)

while True:
    if transcribe_response.output.task_status in ('SUCCEEDED', 'FAILED'):
        break
    transcribe_response = Transcription.fetch(task=transcribe_response.output.task_id)

if transcribe_response.status_code == HTTPStatus.OK:
    print(json.dumps(transcribe_response.output, indent=4, ensure_ascii=False))
    print('Transcription done!')

Sensitive word filter

By default, words matching the built-in sensitive word list (Chinese) are replaced with * characters.

Pass a JSON string to special_word_filter to customize this behavior:

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

TranscriptionResponse

Both wait() and fetch() return a TranscriptionResponse object.

The async_call() return value contains only task_id and task_status. Call wait() or fetch() for the full response including submit_time, results, and usage.

Successful response example (from wait() or fetch()):

{
    "status_code": 200,
    "request_id": "16668704-6702-9e03-8ab7-a32a5d7bb095",
    "code": null,
    "message": "",
    "output": {
        "task_id": "6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-02-13 17:31:20.681",
        "scheduled_time": "2025-02-13 17:31:20.703",
        "end_time": "2025-02-13 17:31:21.867",
        "results": [
            {
                "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
                "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/...",
                "subtask_status": "SUCCEEDED"
            },
            {
                "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
                "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/...",
                "subtask_status": "SUCCEEDED"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "duration": 9
    }
}

Response fields:

Partial failure example

When some files fail, the overall task status may still be SUCCEEDED. Always check subtask_status for each file:

{
    "results": [
        {
            "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
            "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/...",
            "subtask_status": "SUCCEEDED"
        },
        {
            "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"
        }
    ]
}

Recognition result JSON

Download the JSON file from transcription_url to access detailed transcription data:

{
    "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
    "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 Alibaba Speech Lab.",
            "sentences": [
                {
                    "begin_time": 100,
                    "end_time": 3820,
                    "text": "Hello world, this is Alibaba Speech Lab.",
                    "sentence_id": 1,
                    "speaker_id": 0,
                    "words": [
                        {
                            "begin_time": 100,
                            "end_time": 596,
                            "text": "Hello ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 596,
                            "end_time": 844,
                            "text": "world",
                            "punctuation": ", "
                        }
                    ]
                }
            ]
        }
    ]
}

speaker_id appears only when diarization_enabled=True. Speech content duration (content_duration_in_milliseconds) is typically shorter than the original audio duration because only speech is measured. An AI model determines speech presence, so discrepancies may occur.

Recognition result fields:

Transcription class

Import: from dashscope.audio.asr import Transcription

Does the service accept base64-encoded audio?

No. Only publicly accessible HTTP/HTTPS URLs are supported. Local files and binary streams cannot be used.

How do I host audio files as accessible URLs?

Upload files to Alibaba Cloud OSS and use the generated URL (format: https://<bucket-name>.<region>.aliyuncs.com/<file-name>).

Alternatives include hosting on a web server (Nginx, Apache) or a CDN. Verify URL accessibility in a browser or with curl.

How long does transcription take?

After submission, tasks queue in PENDING state. Queue time depends on queue length and file duration (typically a few minutes). Once processing starts, recognition runs hundreds of times faster than real-time.

Timestamps are not aligned with audio playback

Set timestamp_alignment_enabled=True in the request parameters.

Polling returns no result

This may be caused by rate limiting. Request a quota increase via the GitHub repository.

No speech is recognized

1. Verify audio format and sample rate match model requirements.

2. For paraformer-v2, check that language_hints includes the correct language codes.

3. Use custom hotwords to improve recognition of domain-specific terms.