Skip to main content
阿里云百炼 home page阿里云百炼
非实时语音识别（Paraformer）

Paraformer非实时语音识别Python SDK

本文介绍Paraformer非实时语音识别Python SDK的参数和接口细节。

阿里云百炼为华北2（北京）地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com。{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。
用户指南：非实时语音识别

前提条件

已开通服务并获取与配置 API Key。请配置API Key到环境变量，而非硬编码在代码中，防范因代码泄露导致的安全风险。
当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时鉴权Token。与长期有效的 API Key 相比，临时鉴权 Token 具备时效性短（60秒）、安全性高的特点，适用于临时调用场景，能有效降低API Key泄露的风险。使用方式：在代码中，将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。

快速开始

核心类（Transcription）提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行非实时语音识别：
  • 异步提交任务+同步等待任务结束：提交任务后，阻塞当前线程直到任务结束并获取识别结果。
  • 异步提交任务+异步查询任务执行结果：提交任务后，在需要的时候通过调用查询任务接口获取任务的执行结果。

异步提交任务+同步等待任务结束

image
  1. 调用核心类（Transcription）的async_call方法并设置请求参数。
    • 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内。任务开始处理后，语音识别将以数百倍加速完成。
    • 每一个任务完成后，识别结果和URL下载链接有效期为24小时，超时后无法查询任务或通过先前查询结果中的URL下载结果。
  2. 调用核心类（Transcription）的wait方法同步等待任务结束。 任务的状态包括PENDING、RUNNING、SUCCEEDED和FAILED。当任务处于PENDING或RUNNING状态时，wait接口将被阻塞。当任务处于SUCCEEDED或FAILED状态时，wait接口不再阻塞并返回任务的执行结果。 wait返回TranscriptionResponse。 
from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import json

# 若没有将API Key配置到环境变量中，需将下面这行代码注释放开，并将apiKey替换为自己的API Key
# dashscope.api_key = "apiKey"
# 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

task_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # “language_hints”只支持paraformer-v2模型
)

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!')

异步提交任务+异步查询任务执行结果

image
  1. 调用核心类（Transcription）的async_call方法并设置请求参数。
    • 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内。任务开始处理后，语音识别将以数百倍加速完成。
    • 每一个任务完成后，识别结果和URL下载链接有效期为24小时，超时后无法查询任务或通过先前查询结果中的URL下载结果。
  2. 循环调用核心类（Transcription）的fetch方法直到获取最终的任务结果。 当任务状态为SUCCEEDED或FAILED时，停止轮询并处理结果。 fetch返回TranscriptionResponse。 
from http import HTTPStatus
from dashscope.audio.asr import Transcription
import json
# 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# 若没有将API Key配置到环境变量中，需将下面这行代码注释放开，并将apiKey替换为自己的API Key
# import dashscope
# dashscope.api_key = "apiKey"

transcribe_response = Transcription.async_call(
    model='paraformer-v2',
    file_urls=['{YOUR_AUDIO_URL}'],
    language_hints=['zh', 'en']  # “language_hints”只支持paraformer-v2模型
)

while True:
    if transcribe_response.output.task_status == 'SUCCEEDED' or transcribe_response.output.task_status == '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!')

请求参数

请求参数通过核心类（Transcription）的async_call方法进行设置。
说话人分离功能（diarization_enabled）仅适用于单声道音频，多声道音频不支持说话人分离。如果您的音频为多声道格式，需先将其转换为单声道后再启用说话人分离。可使用ffmpeg进行转换：ffmpeg -i input.wav -ac 1 output_mono.wav。
参数类型默认值是否必须说明
modelstr
是指定用于音视频文件转写的Paraformer模型名。参见支持的模型。
file_urlslist[str]
是音视频文件转写的URL列表，支持HTTP / HTTPS协议，单次请求仅支持1个URL。若录音文件存储在阿里云OSS，使用SDK方式不支持使用以 oss://为前缀的临时 URL。
vocabulary_idstr
否最新热词ID，支持最新v2系列模型并配置语种信息，此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。
phrase_idstr
否热词ID，此次语音识别中生效此热词ID对应的热词信息。默认不启用。注：phrase_id为v1版本模型热词方案，不支持v2及后续系列模型。支持该方式热词的模型列表请参考Paraformer语音识别热词定制与管理。
channel_idlist[int][0]否指定在多音轨音频文件中需要识别的音轨索引，索引从 0 开始。例如，[0] 表示识别第一个音轨，[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数，则默认处理第一个音轨。
指定的每一个音轨都将独立计费。例如，为单个文件请求 [0, 1] 会产生两笔独立的费用。
disfluency_removal_enabledboolFalse否过滤语气词，默认关闭。
timestamp_alignment_enabledboolFalse否是否启用时间戳校准功能，默认关闭。
special_word_filterstr
否指定在语音识别过程中需要处理的敏感词，并支持对不同敏感词设置不同的处理方式。若未传入该参数，系统将启用系统内置的敏感词过滤逻辑，识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的*。若传入该参数，则可实现以下敏感词处理策略：
  • 替换为 *：将匹配的敏感词替换为等长的 *；
  • 直接过滤：将匹配的敏感词从识别结果中完全移除。
该参数的值应为一个 JSON 字符串，其结构如下所示：
{
  "filter_with_signed": {
    "word_list": ["测试"]
  },
  "filter_with_empty": {
    "word_list": ["开始", "发生"]
  },
  "system_reserved_filter": true
}
JSON字段说明：
  • filter_with_signed
    • 类型：对象。
    • 是否必填：否。
    • 描述：配置需替换为*的敏感词列表。识别结果中匹配的词语将被等长的 * 替代。
    • 示例：以上述JSON为例，“帮我测试一下这段代码”的语音识别结果将会是“帮我**一下这段代码”。
    • 内部字段：
      • word_list: 字符串数组，列出需被替换的敏感词。
  • filter_with_empty
    • 类型：对象。
    • 是否必填：否。
    • 描述：配置需从识别结果中移除（过滤）的敏感词列表。识别结果中匹配的词语将被完全删除。
    • 示例：以上述JSON为例，“比赛这就要开始了吗？”的语音识别结果将会是“比赛这就要了吗”。
    • 内部字段：
      • word_list: 字符串数组，列出需被完全移除（过滤）的敏感词。
  • system_reserved_filter
    • 类型：布尔值。
    • 是否必填：否。
    • 默认值：true。
    • 描述：是否启用系统预置的敏感词规则。设为true时，将同时启用系统内置的敏感词过滤逻辑，识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的*。
language_hintslist[str]["zh", "en"]否指定待识别语音的语言代码。该参数仅适用于paraformer-v2模型。支持的语言代码：
  • zh: 中文
  • en: 英文
  • ja: 日语
  • yue: 粤语
  • ko: 韩语
  • de：德语
  • fr：法语
  • ru：俄语
diarization_enabledboolFalse否自动说话人分离，默认关闭。仅适用于单声道音频，多声道音频不支持说话人分离。启用该功能后，识别结果中将显示speaker_id字段，用于区分不同说话人。
如果启用说话人分离功能，建议音频时长不超过2小时，否则可能导致识别失败或超时。
有关speaker_id的示例，请参见识别结果说明。
speaker_countint
否说话人数量参考值。取值范围为2至100的整数（包含2和100）。开启说话人分离功能后（diarization_enabled设置为true）生效。默认自动判断说话人数量，如果配置此项，只能辅助算法尽量输出指定人数，无法保证一定会输出此人数。

响应结果

TranscriptionResponse

TranscriptionResponse封装了任务的基本信息（task_id和task_status）和执行结果（output属性对应的内容，参见TranscriptionOutput）。
async_call方法返回的TranscriptionResponse示例如下，不包含submit_time、scheduled_time等信息：
{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING"
    },
    "usage":null
}
如果需要获取submit_time、scheduled_time等信息，应使用wait()或fetch()方法，而不是直接从 async_call() 的返回值中访问。wait()或fetch()方法返回的TranscriptionResponse示例如下：
{
    "status_code":200,
    "request_id":"251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
    "code":null,
    "message":"",
    "output":{
        "task_id":"7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
        "task_status":"PENDING",
        "submit_time":"2025-02-13 16:55:08.573",
        "scheduled_time":"2025-02-13 16:55:08.592",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":0,
            "FAILED":0
        }
    },
    "usage":null
}
需要关注的参数：

参数

说明

status_code

HTTP请求状态码。

code

  • 最外层的code不必关注。

  • output.results下面的code，代表错误码。可以结合message字段，对照错误码排查问题。

message

  • 最外层的message不必关注。

  • output.results下面的message，代表错误信息。可以结合code字段，对照错误码排查问题。

task_id

任务ID。

task_status

任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为SUCCEEDED，需通过subtask_status字段判断具体子任务结果。

results

子任务识别结果。

subtask_status

子任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

file_url

被识别音频的URL。

transcription_url

音频识别结果对应的URL。

识别结果保存为JSON文件，您可以通过transcription_url对应的链接下载文件或直接通过HTTP请求读取该文件中的内容。JSON文件的内容请参见识别结果说明。

TranscriptionOutput

TranscriptionOutput对应TranscriptionResponse的output属性，代表当前任务执行结果。
  • PENDING状态
  • RUNNING状态
  • SUCCEEDED 状态
  • FAILED 状态
{
    "task_id":"f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
    "task_status":"PENDING",
    "submit_time":"2025-02-13 17:59:27.754",
    "scheduled_time":"2025-02-13 17:59:27.789",
    "task_metrics":{
        "TOTAL":1,
        "SUCCEEDED":0,
        "FAILED":0
    }
}
需要关注的参数：

参数

说明

code

代表错误码。可以结合message字段，对照错误码排查问题。

message

代表错误信息。可以结合code字段，对照错误码排查问题。

task_id

任务ID。

task_status

任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为SUCCEEDED，需通过subtask_status字段判断具体子任务结果。

results

子任务识别结果。

subtask_status

子任务状态。

有PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。

file_url

被识别音频的URL。

transcription_url

音频识别结果对应的URL。

识别结果以JSON格式保存在一个JSON文件中，您可以通过transcription_url对应的链接下载文件或直接通过HTTP请求读取该文件中的内容。JSON文件的内容请参见识别结果说明。

识别结果说明

识别结果保存为JSON文件。 
{
    "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, 这里是阿里巴巴语音实验室。",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, 这里是阿里巴巴语音实验室。",
                    "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":", "
                        }
                        // 这里省略其它内容
                    ]
                }
            ]
        }
    ]
}
需要关注的参数如下：

参数

类型

说明

audio_format

string

源文件中音频的格式。

channels

array[integer]

源文件中音频的音轨索引信息，对单轨音频返回[0]，对双轨音频返回[0, 1]，以此类推。

original_sampling_rate

integer

源文件中音频的采样率（Hz）。

original_duration

integer

源文件中的原始音频时长（ms）。

channel_id

integer

转写结果的音轨索引，以0为起始。

content_duration

integer

音轨中被判定为语音内容的时长（ms）。

Paraformer语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写，并据此进行计量计费，非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的，可能与实际情况存在一定误差。

transcript

string

段落级别的语音转写结果。

sentences

array

句子级别的语音转写结果。

words

array

词级别的语音转写结果。

begin_time

integer

开始时间戳（ms）。

end_time

integer

结束时间戳（ms）。

text

string

语音转写结果。

speaker_id

integer

当前说话人的索引，以0为起始，用于区分不同的说话人。

仅在启用说话人分离功能时，该字段才会显示于识别结果中。

punctuation

string

预测出的词之后的标点符号（如有）。

关键接口

核心类（Transcription）

Transcription可以通过“from dashscope.audio.asr import Transcription”方式引入。
成员方法方法签名说明
async_call
@classmethod
def async_call(cls,
               model: str,
               file_urls: List[str],
               phrase_id: str = None,
               api_key: str = None,
               workspace: str = None,
               **kwargs) -> TranscriptionResponse
异步提交语音识别任务。该方法返回TranscriptionResponse。
wait
@classmethod
def wait(cls,
         task: Union[str, TranscriptionResponse],
         api_key: str = None,
         workspace: str = None,
         **kwargs) -> TranscriptionResponse
阻塞当前线程直到异步任务结束（任务状态为SUCCEEDED或FAILED）。该方法返回TranscriptionResponse。
fetch
@classmethod
def fetch(cls,
          task: Union[str, TranscriptionResponse],
          api_key: str = None,
          workspace: str = None,
          **kwargs) -> TranscriptionResponse
异步查询当前任务执行结果。该方法返回TranscriptionResponse。

其他接口：批量查询任务状态/取消任务

详情请参见管理异步任务：支持批量查询24小时内提交的非实时语音识别任务，同时支持取消PENDING（排队）状态的任务。

错误码

如遇报错问题，请参见错误码进行排查。 若问题仍未解决，请加入开发者群反馈遇到的问题，并提供Request ID，以便进一步排查问题。 当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为SUCCEEDED，需通过subtask_status字段判断具体子任务结果。 错误返回示例： 
{
    "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-12-16 16:30:59.170",
    "scheduled_time": "2024-12-16 16:30:59.204",
    "end_time": "2024-12-16 16:31:02.375",
    "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
    }
}

更多示例

更多示例，请参见GitHub。

常见问题

功能特性

Q：是否支持Base64编码方式的音频？

不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别，不支持识别二进制流，也不支持直接识别本地文件。

Q：如何将音频文件以公网可访问的URL形式提供？

通常遵循以下几个步骤（这里为您提供一种思路，具体情况因不同存储产品而异，推荐将音频上传至阿里云OSS）：
如以下这几种：
  • 对象存储服务（推荐）：
    • 使用云服务商的对象存储服务（如阿里云OSS），将音频文件上传到存储桶中，并设置为公开访问。
    • 优点：高可用性、支持 CDN 加速、易于管理。
  • Web 服务器：
    • 将音频文件放置在支持 HTTP/HTTPS 访问的 Web 服务器上（如 Nginx、Apache）。
    • 优点：适合小型项目或本地测试。
  • 内容分发网络（CDN）：
    • 将音频文件托管在 CDN 上，通过 CDN 提供的 URL 访问。
    • 优点：加速文件传输，适合高并发场景。
根据选择的存储/托管方式，将音频上传，如：
  • 对象存储服务：
    • 登录云服务商的控制台，创建存储桶。
    • 上传音频文件，并设置文件权限为“公共读”或生成临时访问链接。
  • Web 服务器：
    • 将音频文件放置在服务器指定目录下（如 /var/www/html/audio/）。
    • 确保文件可以通过 HTTP/HTTPS 访问。
例如：
  • 对象存储服务：
    • 文件上传后，系统会自动生成一个公网访问 URL（通常格式为 https://<bucket-name>.<region>.aliyuncs.com/<file-name>）。
    • 如果需要更友好的域名，可以绑定自定义域名并开启 HTTPS。
  • Web 服务器：
    • 文件的访问 URL 通常是服务器地址加上文件路径（如 https://your-domain.com/audio/file.mp3）。
  • CDN：
    • 配置 CDN 加速后，使用 CDN 提供的 URL（如 https://cdn.your-domain.com/audio/file.mp3）。
公网环境下，确保生成的 URL 可以正常访问，例如：
  • 在浏览器中打开 URL，检查是否能播放音频文件。
  • 使用工具（如 curl 或 Postman）验证 URL 是否返回正确的 HTTP 响应（状态码 200）。
使用SDK时，若录音文件存储在阿里云OSS，不支持使用以 oss://为前缀的临时 URL。 使用RESTful API时，若录音文件存储在阿里云OSS，支持使用以 oss://为前缀的临时 URL：
  • 临时 URL 有效期48小时，过期后无法使用，请勿用于生产环境。
  • 文件上传凭证接口限流为 100 QPS 且不支持扩容，请勿用于生产环境、高并发及压测场景。
  • 生产环境建议使用阿里云OSS 等稳定存储，确保文件长期可用并规避限流问题。

Q：多久能获取识别结果？

任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内，请耐心等待。并且音频时长越长，所需时间越久。

故障排查

如遇代码报错问题，请根据错误码中的信息进行排查。

Q：识别结果和语音播放不同步怎么办？

将请求参数timestamp_alignment_enabled设为true将启用时间戳校准功能，能够让识别结果和语音播放同步。

Q：一直轮询不到结果？

可能是限流原因，请耐心等待。若需扩容，请加入开发者群进行申请。

Q：无法识别语音（无识别结果）是什么原因？

  • 请检查音频是否符合要求（格式、采样率）。
  • 若是使用了paraformer-v2模型，检查language_hints的设置是否正确。
  • 以上都没问题，可通过定制热词，提升对特定词语的识别效果。

Q：说话人分离结果全部标记为同一个Speaker怎么办？

请按以下步骤排查：
  1. 检查音频是否为单声道格式。说话人分离功能仅支持单声道音频，多声道音频不支持说话人分离。可使用ffprobe查看音频声道数：ffprobe -i input.wav -show_entries stream=channels -of default=noprint_wrappers=1。
  2. 如果音频为多声道，需先转换为单声道：ffmpeg -i input.wav -ac 1 output_mono.wav。
  3. 确认已正确设置说话人分离参数：diarization_enabled=true，并根据实际说话人数设置speaker_count参数（取值范围2至100）。

更多问题

请参见GitHub QA。
阿里云百炼 home page阿里云百炼
使用 API
文本生成
图像生成
视频生成
3D模型生成
音频
实时多模态
Realtime API
  • 概述
向量与排序
更多模型
工具包/框架
模型生产
文件管理
更多