Paraformer录音文件识别RESTful API

本文介绍Paraformer录音文件识别RESTful API的使用。

目前提供了提交任务接口查询任务接口,通常情况下,您可以先调用提交任务接口上传识别任务,然后循环调用查询任务接口,直至任务完成。

前提条件

已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。

模型列表

模型名

模型简介

paraformer-v2

推荐使用。Paraformer最新多语种语音识别模型。

  • 适用场景:直播、会议等场景的多语种识别

  • 支持的采样率:任意

  • 支持的语种:中文(包含中文普通话和各种方言)、英文、日语、韩语、德语、法语、俄语

    支持的中文方言(单击查看详情)

    上海话、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、江西话、宁夏话、山西话、陕西话、山东话、四川话、天津话、云南话、粤语

  • 核心能力:

    • 支持标点符号预测

    • 支持逆文本正则化(ITN)

  • 特色功能:

    • 指定语种:通过language_hints参数能够指定待识别语种,提升识别效果

    • 支持定制热词

paraformer-8k-v2

推荐使用。Paraformer最新中文语音识别模型,模型结构升级,具有更好的识别效果。

  • 适用场景:电话客服、语音信箱等场景的中文识别

  • 支持的采样率:8kHz

  • 支持的语种:中文

  • 核心能力:

    • 支持标点符号预测

    • 支持逆文本正则化(ITN)

  • 特色功能:

paraformer-v1

Paraformer中英文语音识别模型。

  • 适用场景:访谈、讲座等中英文混合场景

  • 支持的采样率:任意

  • 支持的语种:中文、英文

  • 核心能力:

    • 支持标点符号预测

    • 支持逆文本正则化(ITN)

  • 特色功能:

paraformer-8k-v1

Paraformer中文语音识别模型。

  • 适用场景:电话客服、语音信箱等8kHz采样率音频处理

  • 支持的采样率:8kHz

  • 支持的语种:中文

  • 核心能力:

    • 支持标点符号预测

    • 支持逆文本正则化(ITN)

  • 特色功能:

paraformer-mtl-v1

Paraformer多语言语音识别模型。

  • 适用场景:国际会议、访谈等多语种交替发言场景

  • 支持的采样率:16kHz及以上

  • 支持的语种:中文普通话、中文方言(粤语、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、宁夏话、山西话、陕西话、山东话、四川话、天津话)、英语、日语、韩语、西班牙语、印尼语、法语、德语、意大利语、马来语

  • 核心能力:

    • 支持标点符号预测

    • 支持逆文本正则化(ITN)

  • 特色功能:

约束

服务不支持本地音视频文件直传,输入源需为可通过公网访问的文件URL(支持HTTP/HTTPS协议,示例:https://your-domain.com/file.mp3)。URL通过file_urls参数指定,单次请求最多支持100URL。

  • 音频格式

    aacamraviflacflvm4amkvmovmp3mp4mpegoggopuswavwebmwmawmv

    重要

    由于音视频格式及其变种众多,技术上无法穷尽测试,API不能保证所有格式均能够被正确识别。请通过测试验证您所提供的文件能够获得正常的语音识别结果。

  • 音频采样率

    采样率因模型而异:

    • paraformer-v2 支持任意采样率

    • paraformer-v1 支持任意采样率

    • paraformer-8k-v2 仅支持8kHz采样率

    • paraformer-8k-v1 仅支持8kHz采样率

    • paraformer-mtl-v1 支持16kHz及以上采样率

  • 音频文件大小和时长

    音频文件不超过2GB;时长在12小时以内。

    如果希望处理的文件超过了上述限制,可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率

  • 批处理音频数目

    单次请求最多支持100个文件URL。

  • 可识别语言

    因模型而异:

    • paraformer-v2:

      • 中文,包含中文普通话和各种方言:上海话、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、江西话、宁夏话、山西话、陕西话、山东话、四川话、天津话、云南话、粤语

      • 英文

      • 日语

      • 韩语

    • paraformer-8k-v2 仅支持中文

    • paraformer-v1 仅支持中英文

    • paraformer-8k-v1 仅支持中文

    • paraformer-mtl-v1:中文普通话、中文方言(粤语、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、宁夏话、山西话、陕西话、山东话、四川话、天津话)、英语、日语、韩语、西班牙语、印尼语、法语、德语、意大利语、马来语。

  • 接口调用方式限制

    不支持前端直接调用API,需通过后端中转。

提交任务接口

基本信息

接口描述

提交语音识别任务。

URL

https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription

请求方法

POST

请求头

Authorization: Bearer {api-key} // 需替换为您自己的API Key
Content-Type: application/json
X-DashScope-Async: enable

消息体

包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略:

{
    "model":"paraformer-v2", //模型名,必选
    "input":{
        "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"
        ] //待识别文件,必选
    },
    "resources": [
        {
            "resource_id": "xxxxxxxxxxxx", //旧版热词ID,可选
            "resource_type": "asr_phrase"  //固定值“asr_phrase”,和resource_id搭配使用
        }
    ],
    "parameters":{
        "vocabulary_id":"vocab-Xxxx", //最新热词ID,可选
        "channel_id":[
            0
        ], //音轨索引,可选
        "disfluency_removal_enabled":false, //过滤语气词开关,可选
        "timestamp_alignment_enabled": false, //是否启用时间戳校准功能,可选
        "special_word_filter": "xxx", //敏感词,可选
        "language_hints":[
            "zh",
            "en"
        ],
        "diarization_enabled":false, //自动说话人分离,可选
        "speaker_count": 2 //说话人数量参考,可选
    }
}

请求参数

点击查看请求示例

以下为调用提交任务接口的cURL示例:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{"model":"paraformer-v2","input":{"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"]},"parameters":{"channel_id":[0]}}'

参数

类型

默认值

是否必须

说明

model

string

-

指定用于音视频文件转写的Paraformer模型名。参见模型列表

file_urls

array[string]

-

音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求最多支持100URL。

vocabulary_id

string

-

最新热词ID,支持最新v2系列模型并配置语种信息,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词

resource_id

string

-

热词ID,此次语音识别中生效此热词ID对应的热词信息。默认不启用。

注:resource_id对应SDK中的phrase_id字段,phrase_idv1版本模型热词方案,不支持v2及后续系列模型。支持该方式热词的模型列表请参考Paraformer语音识别热词定制与管理

resource_type

string

-

固定字符串"asr_phrase",和"resource_id"需同时使用。

channel_id

array[integer]

[0]

指定在多音轨文件中需要进行语音识别的音轨索引,以List的形式给出,例如[0]表示仅识别第一条音轨,[0, 1]表示同时识别前两条音轨。

disfluency_removal_enabled

boolean

false

过滤语气词,默认关闭。

timestamp_alignment_enabled

boolean

false

是否启用时间戳校准功能,默认关闭。

special_word_filter

string

-

敏感词过滤功能,支持开启或关闭,支持自定义敏感词。该参数可实现:

不处理(默认,即展示原文)、过滤、替换为*。

说明

开启但未配置敏感词,则会过滤默认词表:敏感词表

language_hints

array[string]

["zh", "en"]

指定待识别语音的语言代码。

该参数仅适用于paraformer-v2模型。

支持的语言代码:

  • zh: 中文

  • en: 英文

  • ja: 日语

  • yue: 粤语

  • ko: 韩语

  • de:德语

  • fr:法语

  • ru:俄语

diarization_enabled

boolean

false

自动说话人分离,默认关闭。

仅适用于单声道音频,多声道音频不支持说话人分离。

启用该功能后,识别结果中将显示speaker_id字段,用于区分不同说话人。

有关speaker_id的示例,请参见识别结果说明

speaker_count

integer

-

说话人数量参考值。取值范围为2100的整数(包含2100)。

开启说话人分离功能后(diarization_enabled设置为true)生效。

默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。

响应参数

点击查看响应示例

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

参数

类型

说明

task_status

string

任务状态。

task_id

string

任务ID。

查询任务接口

基本信息

接口描述

查询语音识别任务执行情况和结果。

URL

https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

请求方法

POST

请求头

Authorization: Bearer {api-key} // 需替换为您自己的API Key

消息体

无。

请求参数

点击查看请求示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' --header "Authorization: Bearer $DASHSCOPE_API_KEY"

参数

类型

默认值

是否必须

说明

task_id

string

-

查询任务需指定其ID,该ID提交任务接口被调用后返回的task_id

响应参数

点击查看响应示例

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

正常示例

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "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/pre/filetrans-16k/20240912/15%3A11/3bdf7689-b598-409d-806a-121cff5e4a31-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=Fj%2BaF%2FH0Kayj3w3My2ECBeP****%3D",
        "subtask_status": "SUCCEEDED"
      },
      {
        "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/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

异常示例

code”为错误码,“message”为错误信息,只有异常情况才有这两个字段,您可以通过这两个字段,对照错误码排查问题。

{
    "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": "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/prod/paraformer-v2/20241216/xxxx",
            "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"
        }
    ],
    "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 1,
        "FAILED": 1
    }
}

参数

类型

说明

task_id

string

被查询任务的ID。

task_status

string

被查询任务的状态。

说明

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

subtask_status

string

子任务状态。

file_url

string

文件转写任务中所处理的文件URL。

transcription_url

string

获取识别结果对应的链接。该链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。

识别结果保存为JSON文件,您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。

JSON数据中各字段含义请参见识别结果说明

识别结果说明

识别结果保存为JSON文件。

点击查看识别结果示例

{
    "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, 这里是阿里巴巴语音实验室。",
            "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

预测出的词之后的标点符号(如有)。

完整示例

您可以使用编程语言自带的HTTP类库,来实现提交和查询任务的请求:先调用提交任务接口上传识别任务,然后循环调用查询任务接口,直至任务完成。

Python为例,代码如下:

import requests
import json
import time

api_key = "your-dashscope-api-key"  # 在此处替换为您的API Key
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"]


# 提交文件转写任务,包含待转写文件url列表
def submit_task(apikey, file_urls) -> str:

    headers = {
        "Authorization": f"Bearer {apikey}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable",
    }
    data = {
        "model": "paraformer-v2",
        "input": {"file_urls": file_urls},
        "parameters": {
            "channel_id": [0],
            "language_hints": language_hints,
            "vocabulary_id": "vocab-Xxxx",
        },
    }
    # 录音文件转写服务url
    service_url = (
        "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription"
    )
    response = requests.post(
        service_url, headers=headers, data=json.dumps(data)
    )

    # 打印响应内容
    if response.status_code == 200:
        return response.json()["output"]["task_id"]
    else:
        print("task failed!")
        print(response.json())
        return None


# 循环查询任务状态直到成功
def wait_for_complete(task_id):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "X-DashScope-Async": "enable",
    }

    pending = True
    while pending:
        # 查询任务状态服务url
        service_url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
        response = requests.post(
            service_url, headers=headers
        )
        if response.status_code == 200:
            status = response.json()['output']['task_status']
            if status == 'SUCCEEDED':
                print("task succeeded!")
                pending = False
                return response.json()['output']['results']
            elif status == 'RUNNING' or status == 'PENDING':
                pass
            else:
                print("task failed!")
                pending = False
        else:
            print("query failed!")
            pending = False
        print(response.json())
        time.sleep(0.1)


task_id = submit_task(apikey=api_key, file_urls=file_urls)
print("task_id: ", task_id)
result = wait_for_complete(task_id)
print("transcription result: ", result)

错误码

当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为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": "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/prod/paraformer-v2/20241216/xxxx",
            "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"
        }
    ],
    "task_metrics": {
        "TOTAL": 2,
        "SUCCEEDED": 1,
        "FAILED": 1
    }
}

语音相关错误码:

错误码(code)

原因

解决方案

SUCCESS_WITH_NO_VALID_FRAGMENT

识别结果查询接口调用成功,但是VAD模块未检测到有效语音。

此种情况下可检查:

录音文件是否包含有效语音,如果都是无效语音,例如纯静音。上述情况下没有识别结果是正常现象。

ASR_RESPONSE_HAVE_NO_WORDS

识别结果查询接口调用成功,但是最终识别结果为空。

此种情况下可检查:

录音文件是否包含有效语音,或有效语音是否都是语气词且开启了顺滑参数disfluency_removal_enabled,导致语气词被过滤。

FILE_DOWNLOAD_FAILED

文件下载失败。

检查录音文件路径是否正确,以及是否可以通过外网访问和下载。

FILE_CHECK_FAILED

文件格式错误。

检查录音文件是否是单轨/双轨的WAV格式或MP3格式。

FILE_TOO_LARGE

文件过大。

检查录音文件大小是否超过2GB,超过则需您对录音文件分段。

FILE_NORMALIZE_FAILED

文件归一化失败。

检查录音文件是否有损坏,是否可以正常播放。

FILE_PARSE_FAILED

文件解析失败。

检查录音文件是否有损坏,是否可以正常播放。

MKV_PARSE_FAILED

MKV解析失败。

检查录音文件是否损坏,是否可以正常播放。

FILE_TRANS_TASK_EXPIRED

录音文件识别任务过期。

TaskId不存在,或者已过期。

REQUEST_INVALID_FILE_URL_VALUE

请求file_link参数非法。

确认file_url参数格式是否正确。

CONTENT_LENGTH_CHECK_FAILED

content-length 检查失败。

检查下载文件时,HTTP response中的content-length与文件实际大小是否一致。

FILE_404_NOT_FOUND

需要下载的文件不存在。

检查需要下载的文件是否存在。

FILE_403_FORBIDDEN

没有权限下载需要的文件。

检查是否有权限下载录音文件。

FILE_SERVER_ERROR

请求的文件所在的服务不可用。

检查请求的文件所在的服务是否可用。

AUDIO_DURATION_TOO_LONG

请求的文件时长超过12小时。

建议将音频进行切分,分多次提交识别任务。

使用ffmpeg工具对音频文件进行切分

工具下载:

下载地址:https://ffmpeg.en.lo4d.com/download

命令用法:

以下是一个示例命令,用于从长音频中提取指定时间段的内容:

ffmpeg -i input_audio.wav -ss 00:10:00 -to 5:10:00 -c copy output_audio.wav

参数说明:

  • -i input_audio.wav:指定输入文件,即待处理的音频文件input_audio.wav

  • -ss 00:10:00:设置起始时间,表示从原始音频的第10分钟(00:10:00)开始处理。

  • -to 5:10:00:设置结束时间,表示处理到原始音频的第5小时10分钟(5:10:00)为止。

  • -c copy:指定编解码器选项,copy表示直接复制音频数据,不进行重新编码,从而加快处理速度。

  • output_audio.wav:指定输出文件,即生成的音频文件output_audio.wav

通过上述方法,您可以轻松将长音频切分为多个较短的片段,便于后续识别或处理。

DECODER_ERROR

检测音频文件信息失败。

确认文件下载链接中文件为支持的音频格式。

INTERNAL_ERROR

受机器负载、网络等因素导致的异常,通常为偶发出现。

一般重试调用即可恢复,如无法恢复,请联系技术支持人员。

更多百炼平台相关错误码请参考错误信息

更多示例

更多示例,请参见GitHub

常见问题

请参见GitHub QA