Paraformer non-real-time speech recognition Python SDK

​

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.

• Install the latest DashScope SDK.

​

Getting started

• Async submission + sync wait: Submit a task and block until it completes and returns the result.
• Async submission + async polling: Submit a task and poll for results at any time.

​

Async submission + sync wait

1. Call the core resource (client.audio.asr) (jobs.create/transcribe) and set the request parameters.

2. Call the core resource (client.audio.asr) (jobs.wait, or the one-step transcribe) to wait synchronously for the task to complete. Task statuses: PENDING, RUNNING, SUCCEEDED, FAILED. The wait call blocks during PENDING or RUNNING. When the task reaches SUCCEEDED or FAILED, wait returns the result. jobs.wait returns the final-state Job (for the structure, see Response).

import os
import json
import dashscope

# If you have not configured the API Key in an environment variable, replace the following line with your own API Key: api_key="sk-xxx"
# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://cn-beijing.maas.qwencloudapi.com/api/v1",
)

# Submit the recorded file recognition task and wait synchronously for the task to complete
job = client.audio.asr.transcribe(
    ['{YOUR_AUDIO_URL}'],
    model='paraformer-v2',
    parameters={'language_hints': ['zh', 'en']}  # The "language_hints" parameter only supports the paraformer-v2 model.
)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

# Submit a recorded file recognition task
export DASHSCOPE_API_KEY="your-api-key"
# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
export DASHSCOPE_HTTP_BASE_URL="https://cn-beijing.maas.qwencloudapi.com/api/v1"
dashscope transcription create -m paraformer-v2 --file-url "https://example.com/audio.mp3"
# Query the task list
dashscope transcription list

​

Async submission + async polling

1. Call the core resource (client.audio.asr) (jobs.create/transcribe) and set the request parameters.

2. Poll the core resource (client.audio.asr) (jobs.fetch) until the task completes. Stop polling when the status is SUCCEEDED or FAILED and process the result. jobs.fetch returns a Job (for the structure, see Response).

import os
import json
import dashscope

# If you have not configured the API Key in an environment variable, replace the following line with your own API Key: api_key="sk-xxx"
# China North 2 (Beijing). This model is available only in this region.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://cn-beijing.maas.qwencloudapi.com/api/v1",
)

# Submit the recorded file recognition task
job = client.audio.asr.jobs.create(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    parameters={'language_hints': ['zh', 'en']}  # The "language_hints" parameter only supports the paraformer-v2 model.
)

# Poll the task until the final result is returned
while True:
    if job.status == 'SUCCEEDED' or job.status == 'FAILED':
        break
    job = client.audio.asr.jobs.fetch(job.task_id)

print(json.dumps(job.model_dump(), indent=4, ensure_ascii=False))
print('transcription done!')

​

Request parameters

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

​

Response

​

Job

{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING"
}

{
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "status":"PENDING",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}

​

results (subtask recognition results)

{
    "file_url":"{YOUR_AUDIO_URL}",
    "transcription_url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20250213/17%3A59/70e737cc-bf8c-418b-b0c8-83fab192a0fa-1.json?Expires=1739527168&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
    "subtask_status":"SUCCEEDED"
}

{
    "file_url": "{YOUR_AUDIO_URL}",
    "code": "InvalidFile.DownloadFailed",
    "message": "The audio file cannot be downloaded.",
    "subtask_status": "FAILED"
}

​

Recognition result description

{
    "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
                    ]
                }
            ]
        }
    ]
}

​

API reference

​

Core resource (client.audio.asr)

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

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

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

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

​

Other interfaces: Batch query task status / Cancel task

​

Error codes

{
    "request_id": "16668704-6702-9e03-8ab7-a32a5d7bb095",
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "status": "SUCCEEDED",
    "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

​

FAQ

​

Features

​

Q: Does it support Base64-encoded audio?

​

Q: How to provide audio files as publicly accessible URLs?

• 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?

​

Troubleshooting

​

Q: What should I do if the recognition results are out of sync with the audio playback?

​

Q: How do I handle special characters in a file URL?

Q: Unable to get results after continuous polling?

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