Model Studio Paraformer file transcription API

Overview

File transcription is asynchronous. Submit file URLs to obtain a task ID, then wait for or query the task to retrieve each file's transcription. The model performs punctuation prediction and inverse text normalization by default.

Model overview

Use model to specify the transcription model. The example uses paraformer-v2. For supported languages, sample rates, and use cases, see Non-real-time speech recognition.

Prerequisites

• Activate Model Studio, obtain an API key for the workspace, and configure it in the DASHSCOPE_API_KEY environment variable. For instructions, see Obtain and configure an API key.

• Install the DashScope Python SDK. For instructions, see Install the DashScope SDK.

The example uses DashScope Python SDK 1.27.7. Set the DASHSCOPE_WORKSPACE_ID environment variable to the workspace ID to construct the workspace-specific domain for China (Beijing).

Limits

• Provide files through HTTP or HTTPS URLs that the service can download. A request supports up to 100 file URLs. Each file must not exceed 2 GB.

• Supported audio and video file formats include .aac, .amr, .avi, .flac, .flv, .m4a, .mkv, .mov, .mp3, .mp4, .mpeg, .ogg, .opus, .wav, .webm, .wma, and .wmv. A format can have multiple encoding variants, not all of which can be recognized.

• Transcription results and download URLs are valid for 24 hours after the task completes. Retrieve and save results within this period.

The service processes file transcription tasks on a best-effort basis. Queue time depends on the queue length and the duration of files in other tasks. An exact waiting time cannot be provided, but tasks usually leave the queue within a few minutes. Once processing starts, speech recognition runs at several hundred times real-time speed.

To reduce file size, preprocess the file before submitting the transcription task.

Code example

The following Python example transcribes two audio files containing Chinese and English speech, waits for completion, and reads each result JSON. Replace file_urls with the URLs of other files as needed.

import json
import os
from http import HTTPStatus
from urllib.request import urlopen

import dashscope
from dashscope.audio.asr import Transcription

dashscope.api_key = os.environ["DASHSCOPE_API_KEY"]
workspace_id = os.environ["DASHSCOPE_WORKSPACE_ID"]
dashscope.base_http_api_url = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1"
)

response = Transcription.async_call(
    model="paraformer-v2",
    file_urls=[
        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female.wav",
        "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male.wav",
    ],
)
if response.status_code != HTTPStatus.OK:
    raise RuntimeError(f"{response.code}: {response.message}")

response = Transcription.wait(task=response.output.task_id)
if response.status_code != HTTPStatus.OK:
    raise RuntimeError(f"{response.code}: {response.message}")

for result in response.output.get("results", []):
    if result["subtask_status"] == "SUCCEEDED":
        with urlopen(result["transcription_url"]) as audio_result:
            transcription = json.load(audio_result)
        print(json.dumps(transcription, ensure_ascii=False, indent=2))
    else:
        print(result["file_url"], result.get("code"), result.get("message"))

API reference

The core class is dashscope.audio.asr.Transcription. After submitting a task, use wait() to block until completion or fetch() to query the current status.

{
  "status_code": 200,
  "request_id": "<request_id>",
  "code": "",
  "message": "",
  "output": {
    "task_id": "<task_id>",
    "task_status": "PENDING"
  },
  "usage": null
}

{
  "status_code": 200,
  "request_id": "<request_id>",
  "code": null,
  "message": "",
  "output": {
    "task_id": "<task_id>",
    "task_status": "RUNNING"
  },
  "usage": null
}

{
  "status_code": 200,
  "request_id": "<request_id>",
  "code": null,
  "message": "",
  "output": {
    "task_id": "<task_id>",
    "task_status": "SUCCEEDED",
    "results": [
      {
        "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female.wav",
        "transcription_url": "<transcription_url>",
        "subtask_status": "SUCCEEDED"
      }
    ]
  },
  "usage": {"duration": 4}
}

Transcription results

Each successfully transcribed file has a result JSON available through transcription_url. The following excerpt is from the female-voice sample, with only the first two words retained in words. The audio contains Chinese and English speech, so the transcript retains both languages.

{
  "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female.wav",
  "properties": {
    "audio_format": "pcm_s16le",
    "channels": [0],
    "original_sampling_rate": 16000,
    "original_duration_in_milliseconds": 4087
  },
  "transcripts": [
    {
      "channel_id": 0,
      "content_duration_in_milliseconds": 4080,
      "text": "Hello world, 来自阿里巴巴达摩院语音实验室。",
      "sentences": [
        {
          "begin_time": 0,
          "end_time": 4080,
          "text": "Hello world, 来自阿里巴巴达摩院语音实验室。",
          "sentence_id": 1,
          "words": [
            {"begin_time": 0, "end_time": 480, "text": "Hello ", "punctuation": ""},
            {"begin_time": 480, "end_time": 720, "text": "world", "punctuation": ", "}
          ]
        }
      ]
    }
  ]
}

Error handling

For a failed request, check the response's status_code, code, and message. For a failed file subtask, check code and message in output.results[]. For error codes and solutions, see Model Studio error codes.