本文介绍Paraformer非实时语音识别HTTP API的参数和接口细节。
前提条件
已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
提交任务接口
基本信息
| 接口描述 | 提交语音识别任务。 |
| URL | |
| 请求方法 | POST |
| 请求头 | |
| 消息体 | 包含所有请求参数的消息体如下,对于可选字段,在实际业务中可根据需求省略: |
请求参数
点击查看请求示例
点击查看请求示例
| 参数 | 类型 | 默认值 | 是否必须 | 说明 |
|---|---|---|---|---|
| model | string | 是 | 指定用于音视频文件转写的Paraformer模型名。参见支持的模型。 | |
| file_urls | array[string] | 是 | 音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求仅支持1个URL。若录音文件存储在阿里云OSS,使用RESTful API方式支持使用以 oss://为前缀的临时 URL。 | |
| vocabulary_id | string | 否 | 最新热词ID,支持最新v2系列模型并配置语种信息,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。 | |
| resource_id | string | 否 | 热词ID,此次语音识别中生效此热词ID对应的热词信息。默认不启用。注:resource_id对应SDK中的phrase_id字段,phrase_id为v1版本模型热词方案,不支持v2及后续系列模型。支持该方式热词的模型列表请参考Paraformer语音识别热词定制与管理。 | |
| resource_type | string | 否 | 固定字符串"asr_phrase",和"resource_id"需同时使用。 | |
| channel_id | array[integer] | [0] | 否 | 指定在多音轨音频文件中需要识别的音轨索引,索引从 0 开始。例如,[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模型。支持的语言代码:
|
| diarization_enabled | boolean | false | 否 | 自动说话人分离,默认关闭。仅适用于单声道音频,多声道音频不支持说话人分离。启用该功能后,识别结果中将显示speaker_id字段,用于区分不同说话人。如果启用说话人分离功能,建议音频时长不超过2小时,否则可能导致识别失败或超时。 speaker_id的示例,请参见识别结果说明。 |
| speaker_count | integer | 否 | 说话人数量参考值。取值范围为2至100的整数(包含2和100)。开启说话人分离功能后(diarization_enabled设置为true)生效。默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。 |
响应参数
点击查看响应示例
点击查看响应示例
参数 | 类型 | 说明 |
|---|---|---|
task_status | string | 任务状态。 |
task_id | string |
查询任务接口
基本信息
| 接口描述 | 查询语音识别任务执行情况和结果。 |
| URL | |
| 请求方法 | POST |
| 请求头 | |
| 消息体 | 无。 |
请求参数
点击查看请求示例
点击查看请求示例
参数 | 类型 | 默认值 | 是否必须 | 说明 |
|---|---|---|---|---|
task_id | string | - | 是 | 查询任务需指定其ID,该ID为提交任务接口被调用后返回的 |
响应参数
点击查看响应示例
点击查看响应示例
SUCCEEDED,需通过subtask_status字段判断具体子任务结果。- 正常示例
- 异常示例
参数 | 类型 | 说明 |
|---|---|---|
task_id | string | 被查询任务的ID。 |
task_status | string | 被查询任务的状态。 当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 |
subtask_status | string | 子任务状态。 |
file_url | string | 文件转写任务中所处理的文件URL。 |
transcription_url | string | 获取识别结果对应的链接。该链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。 识别结果保存为JSON文件,您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。 JSON数据中各字段含义请参见识别结果说明。 |
识别结果说明
识别结果保存为JSON文件。
点击查看识别结果示例
点击查看识别结果示例
参数 | 类型 | 说明 |
|---|---|---|
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 | 预测出的词之后的标点符号(如有)。 |
其他接口:批量查询任务状态/取消任务
详情请参见管理异步任务:支持批量查询24小时内提交的非实时语音识别任务,同时支持取消PENDING(排队)状态的任务。
完整示例
您可以使用编程语言自带的HTTP类库,来实现提交和查询任务的请求:先调用提交任务接口上传识别任务,然后循环调用查询任务接口,直至任务完成。
以Python为例,代码如下:
错误码
如遇报错问题,请参见错误码进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为SUCCEEDED,需通过subtask_status字段判断具体子任务结果。
错误返回示例:
更多示例
更多示例,请参见GitHub。
常见问题
功能特性
Q:是否支持Base64编码方式的音频?
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
Q:如何将音频文件以公网可访问的URL形式提供?
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
1、选择存储和托管方式
1、选择存储和托管方式
-
对象存储服务(推荐):
- 使用云服务商的对象存储服务(如阿里云OSS),将音频文件上传到存储桶中,并设置为公开访问。
- 优点:高可用性、支持 CDN 加速、易于管理。
-
Web 服务器:
- 将音频文件放置在支持 HTTP/HTTPS 访问的 Web 服务器上(如 Nginx、Apache)。
- 优点:适合小型项目或本地测试。
-
内容分发网络(CDN):
- 将音频文件托管在 CDN 上,通过 CDN 提供的 URL 访问。
- 优点:加速文件传输,适合高并发场景。
2、上传音频文件
2、上传音频文件
-
对象存储服务:
- 登录云服务商的控制台,创建存储桶。
- 上传音频文件,并设置文件权限为“公共读”或生成临时访问链接。
-
Web 服务器:
- 将音频文件放置在服务器指定目录下(如
/var/www/html/audio/)。 - 确保文件可以通过 HTTP/HTTPS 访问。
- 将音频文件放置在服务器指定目录下(如
3、生成公网可访问的URL
3、生成公网可访问的URL
-
对象存储服务:
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
https://<bucket-name>.<region>.aliyuncs.com/<file-name>)。 - 如果需要更友好的域名,可以绑定自定义域名并开启 HTTPS。
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
-
Web 服务器:
- 文件的访问 URL 通常是服务器地址加上文件路径(如
https://your-domain.com/audio/file.mp3)。
- 文件的访问 URL 通常是服务器地址加上文件路径(如
-
CDN:
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
https://cdn.your-domain.com/audio/file.mp3)。
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
4、验证URL的可用性
4、验证URL的可用性
- 在浏览器中打开 URL,检查是否能播放音频文件。
- 使用工具(如
curl或 Postman)验证 URL 是否返回正确的 HTTP 响应(状态码 200)。
oss://为前缀的临时 URL。
使用RESTful API时,若录音文件存储在阿里云OSS,支持使用以 oss://为前缀的临时 URL:
Q:多久能获取识别结果?
任务提交后将进入排队(PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内,请耐心等待。并且音频时长越长,所需时间越久。
故障排查
如遇代码报错问题,请根据错误码中的信息进行排查。
Q:识别结果和语音播放不同步怎么办?
将请求参数timestamp_alignment_enabled设为true将启用时间戳校准功能,能够让识别结果和语音播放同步。
Q:提交任务后返回InvalidFile.DownloadFailed错误怎么办?
请检查文件URL中是否包含空格、中文等特殊字符。如果文件名包含空格(例如"第八节 学生伤害事故处理办法.mp4"),需要将空格替换为%20进行URL编码后再传入file_urls参数。
Q:录音文件URL设置成OSS临时公网访问不通该如何处理?
headers中将X-DashScope-OssResourceResolve设为enable。
不推荐该方式。
Java SDK或者Python SDK不支持对headers进行配置。
Q:一直轮询不到结果?
可能是限流原因,请耐心等待。若需扩容,请加入开发者群进行申请。
Q:无法识别语音(无识别结果)是什么原因?
- 请检查音频是否符合要求(格式、采样率)。
- 若是使用了
paraformer-v2模型,检查language_hints的设置是否正确。 - 以上都没问题,可通过定制热词,提升对特定词语的识别效果。