Paraformer语音识别
支持的领域 / 任务:audio(音频) / asr(语音识别)
Paraformer语音识别提供的文件转写API,能够对常见的音频或音视频文件进行语音识别,并将结果返回给调用者。
新一代语音识别模型paraformer-v2,支持常见的视频直播、电话客服等场景下任意采样率的音频输入,同时可以通过language_hints参数选择语种获得更准确的识别效果。
Paraformer语音识别返回较为丰富的结果供调用者选择使用,包括全文级文字、句子级文字、词和时间戳等。模型默认进行标点符号预测和逆文本正则化。
由于音视频文件的尺寸通常较大,文件传输和语音识别处理均需要时间,文件转写API通过异步调用方式来提交任务。开发者需要通过查询接口,在文件转写完成后获得语音识别结果。文件转写API支持批处理,用户可以单次上传最多100个文件URL,待所有URL转写完成后,用户可以一次性获取全部转写结果。
录音文件识别目前不支持识别本地文件。
模型概览
模型名 | 模型简介 |
paraformer-v2 | 推荐使用 Paraformer最新语音识别模型,支持多个语种的语音识别。可以通过language_hints参数选择语种获得更准确的识别效果,支持任意采样率。 支持的语言包括:中文(包含中文普通话和各种方言)、英文、日语、韩语。支持热词功能,用法请参考定制热词。 |
paraformer-8k-v2 | 推荐使用 Paraformer最新中文语音识别模型,模型结构升级,具有更好的识别效果。仅支持中文热词。用法请参考定制热词。 |
paraformer-v1 | Paraformer中英文语音识别模型,支持任意采样率的音频或视频语音识别。 |
paraformer-8k-v1 | Paraformer中文语音识别模型,支持8kHz电话语音识别。 |
paraformer-mtl-v1 | Paraformer多语言语音识别模型,支持16kHz及以上采样率的音频或视频语音识别。 支持的语种/方言包括:中文普通话、中文方言(粤语、吴语、闽南语、东北话、甘肃话、贵州话、河南话、湖北话、湖南话、宁夏话、山西话、陕西话、山东话、四川话、天津话)、英语、日语、韩语、西班牙语、印尼语、法语、德语、意大利语、马来语。 |
前提条件
通过DashScope SDK实现异步转写音视频文件
调用示例
用以进行语音识别的具体模型通过
model
参数指定。需要进行语音识别的音视频文件通过
file_urls
参数指定,支持HTTP / HTTPS协议的URL。file_urls
参数指定最多100个文件URL进行转写,且文件小于等于2 GB。如果希望处理的文件超过了上述限制,可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率。
API支持当前主流的音视频文件格式,包括:
aac
、amr
、avi
、flac
、flv
、m4a
、mkv
、mov
、mp3
、mp4
、mpeg
、ogg
、opus
、wav
、webm
、wma
、wmv
重要由于音视频格式及其变种众多,技术上无法穷尽测试,API不能保证所有格式均能够被正确识别。请通过测试验证您所提供的文件能够获得正常的语音识别结果。
文件转写API采用异步调用方式,开发者需谨慎处理任务提交、状态查询、获取结果的异步逻辑。
说明文件转写服务对通过API提交的任务采取尽力服务原则进行处理。具体任务的排队等待时间取决于并发的队列长度和其它任务的文件时长,因而无法提供确切等待时间。通常情况下排队等待时间应小于数分钟。一旦结束排队进入处理状态,文件将以数百倍的加速比进行语音识别。
# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html
from http import HTTPStatus
import dashscope
import json
# 如您未将API Key配置到环境变量中,可带上下面这行代码并将your-dashscope-api-key替换成您自己的API Key
# dashscope.api_key = 'your-dashscope-api-key'
task_response = dashscope.audio.asr.Transcription.async_call(
model='paraformer-v2',
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'] # “language_hints”只支持paraformer-v2和paraformer-realtime-v2模型
)
transcribe_response = dashscope.audio.asr.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!')
package com.alibaba.dashscope.sample.transcription;
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.google.gson.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.*;
import java.net.HttpURLConnection;
import java.util.Collections;
import java.util.List;
public class Main {
public static void main(String[] args) {
TranscriptionParam param =
TranscriptionParam.builder()
// 如您未将API Key配置到环境变量中,可带上下面这行代码并将your-dashscope-api-key替换成您自己的API Key
// .apiKey("your-dashscope-api-key")
.model("paraformer-v2")
.fileUrls(
Collections.singletonList(
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
// “language_hints”只支持paraformer-v2和paraformer-realtime-v2模型
.parameter("language_hints", new String[]{"zh", "en"})
.build();
try {
Transcription transcription = new Transcription();
// 提交转写请求
TranscriptionResult result = transcription.asyncCall(param);
// 打印TaskId
System.out.println("TaskId: " + result.getTaskId());
// 等待转写完成
result =
transcription.wait(
TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
// 获取转写结果
List<TranscriptionTaskResult> taskResultList = result.getResults();
if (taskResultList != null && taskResultList.size() > 0) {
TranscriptionTaskResult taskResult = taskResultList.get(0);
// 获取转写结果的url
String transcriptionUrl = taskResult.getTranscriptionUrl();
// 通过Http获取url内对应的结果
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
// 格式化输出json结果
Gson gson = new GsonBuilder().setPrettyPrinting().create();
System.out.println(gson.toJson(gson.fromJson(reader, JsonObject.class)));
}
} catch (Exception e) {
System.out.println("error: " + e);
}
System.exit(0);
}
}
返回结果示例
{
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
"properties": {
"audio_format": "pcm_s16le",
"channels": [
0
],
"original_sampling_rate": 16000,
"original_duration_in_milliseconds": 4726
},
"transcripts": [
{
"channel_id": 0,
"content_duration_in_milliseconds": 4570,
"text": "Hello world, 这里是阿里巴巴语音实验室。",
"sentences": [
{
"begin_time": 140,
"end_time": 4710,
"text": "Hello world, 这里是阿里巴巴语音实验室。",
"words": [
{
"begin_time": 140,
"end_time": 597,
"text": "Hello ",
"punctuation": ""
},
{
"begin_time": 597,
"end_time": 1054,
"text": "world",
"punctuation": ", "
},
{
"begin_time": 1054,
"end_time": 1663,
"text": "这里",
"punctuation": ""
},
{
"begin_time": 1663,
"end_time": 2272,
"text": "是阿",
"punctuation": ""
},
{
"begin_time": 2272,
"end_time": 2881,
"text": "里巴",
"punctuation": ""
},
{
"begin_time": 2881,
"end_time": 3490,
"text": "巴语",
"punctuation": ""
},
{
"begin_time": 3490,
"end_time": 4099,
"text": "音实",
"punctuation": ""
},
{
"begin_time": 4099,
"end_time": 4710,
"text": "验室",
"punctuation": "。"
}
]
}
]
}
]
}
{
"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": 3530,
"text": "Hello world, 这里是阿里巴巴语音实验室。",
"sentences": [
{
"begin_time": 280,
"end_time": 3810,
"text": "Hello world, 这里是阿里巴巴语音实验室。",
"words": [
{
"begin_time": 280,
"end_time": 633,
"text": "Hello ",
"punctuation": ""
},
{
"begin_time": 633,
"end_time": 986,
"text": "world",
"punctuation": ", "
},
{
"begin_time": 986,
"end_time": 1456,
"text": "这里",
"punctuation": ""
},
{
"begin_time": 1456,
"end_time": 1926,
"text": "是阿",
"punctuation": ""
},
{
"begin_time": 1926,
"end_time": 2396,
"text": "里巴",
"punctuation": ""
},
{
"begin_time": 2396,
"end_time": 2866,
"text": "巴语",
"punctuation": ""
},
{
"begin_time": 2866,
"end_time": 3336,
"text": "音实",
"punctuation": ""
},
{
"begin_time": 3336,
"end_time": 3810,
"text": "验室",
"punctuation": "。"
}
]
}
]
}
]
}
返回参数说明
返回参数 | 类型 | 说明 |
audio_format | string | 源文件中音频的格式。 |
channels | List[int] | 源文件中音频的音轨索引信息,对单轨音频返回[0],对双轨音频返回[0, 1],以此类推。 |
original_sampling_rate | int | 源文件中音频的采样率(Hz)。 |
original_duration | int | 源文件中的原始音频时长(ms)。 |
channel_id | int | 表明转写结果的音轨索引,以0为起始。 |
content_duration | int | 音轨中被判定为语音内容的时长(ms)。 重要 Paraformer语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写,并据此进行计量计费,非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的,可能与实际情况存在一定误差。 |
transcript | string | 段落级别的语音转写结果。 |
sentences | List[] | 句子级别的语音转写结果。 |
words | List[] | 词级别的语音转写结果。 |
begin_time | int | 开始时间戳(ms)。 |
end_time | int | 结束时间戳(ms)。 |
text | string | 语音转写结果。 |
punctuation | string | 预测出的词之后的标点符号(如有)。 |
接口详情
当一个文件转写任务成功后,通过wait()
或fetch()
调用可获取文件转写的结果。这个结果同样以文件的形式保存,其链接以transcription_url
给出。开发者可以打开该URL以获取结果。
异步任务文件转写结果文件URL的有效时间是24小时,从异步任务完成的时间开始计算。
异步调用
以异步调用的方式向文件转写服务提交一个任务,返回被提交任务的信息。
接口
dashscope.audio.asr.Transcription.async_call()
TranscriptionResult asyncCall(TranscriptionParam param);
参数配置
参数 | 类型 | 默认值 | 说明 |
model | string | - | 指定用于音视频文件转写的Paraformer模型名,可以从paraformer-v1、paraformer-8k-v1、paraformer-MTL-v1中进行选择。关于如何进行模型选择,请参考:模型概览。 |
file_urls | List[string] | - | 音视频文件转写的URL列表,支持HTTP / HTTPS协议,可最多支持100个文件URL。 |
vocabulary_id(可选) | string | - | 最新热词ID,支持最新v2系列模型并配置语种信息,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词 |
phrase_id (可选) | string | - | 旧版热词ID,此次语音识别中生效的热词ID对应的热词信息。默认不启用。 注:phrase_id为旧版本热词方案,不支持v2及后续系列模型。支持旧版本热词的模型列表请参考Paraformer语音识别热词定制与管理 |
channel_id (可选) | List[int] | [0] | 指定在多音轨文件中需要进行语音识别的音轨索引,以List的形式给出,例如 [0] 代表对第一条音轨进行识别、 [0, 1] 代表对第一和第二条音轨分别进行识别等。 |
disfluency_removal_enabled | boolean | false | 过滤语气词,默认关闭 |
language_hints | List[str] | ['zh', 'en'] | 指定识别语音中语言的代码列表。支持的语言代码:
注:仅对paraformer-v2生效。在java SDK中,此参数需要通过parameter额外参数配置,用法请参考快速开始中示例代码。 |
返回结果示例
{
"status_code": 200,
"request_id": "8c59f00c-7723-455e-922d-ac3a31838170",
"code": "",
"message": "",
"output": {
"task_id": "bd725f8f-f699-4962-bcad-38a9fc2bcd7c",
"task_status": "PENDING"
},
"usage": null
}
返回参数说明
返回参数 | 类型 | 说明 |
code | int | 状态码,详情请参考:错误码 |
task_id | string | 提交的异步任务的ID,该ID作为任务的全局唯一标识符将用于后续对任务状态的查询、结果获取等操作。 |
等待异步任务结束
以阻塞的方式等待异步任务结束(即到达 SUCCEEDED 或 FAILED 状态),返回任务的状态和文件转写结果。异步任务的状态包括 PENDING 、 RUNNING 、 SUCCEEDED 、 FAILED 。当任务处于 PENDING 或 RUNNING 状态时,该调用将被阻塞。当任务处于 SUCCEEDED 或 FAILED 状态时,该调用将返回任务的状态和结果。
接口
dashscope.audio.asr.Transcription.wait()
TranscriptionResult wait(TranscriptionQueryParam param);
参数配置
参数 | 类型 | 默认值 | 说明 |
task | string | - | 在调用提交任务接口时所返回的 task_id 。 |
返回结果示例
{
"status_code": 200,
"request_id": "0411a162-f0df-9196-ba4e-7c4a03788bae",
"code": null,
"message": "",
"output": {
"task_id": "39bfce34-8744-4ee3-a85b-d42cc150908b",
"task_status": "SUCCEEDED",
"submit_time": "2023-10-23 17:41:03.403",
"scheduled_time": "2023-10-23 17:41:03.429",
"end_time": "2023-10-23 17:41:04.022",
"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/paraformer-v2/20231023/17%3A41/4adeaf61-aa36-4a16-81a1-db381d627f06-1.json?Expires=1698140464&OSSAccessKeyId=LTAI5**************4G8qL&Signature=QhsuSA0OCm%2BEBBmdRRF8K4xXP8Q%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/paraformer-v2/20231023/17%3A41/d9b23f85-55c1-43b9-a172-17a7afba3e40-1.json?Expires=1698140464&OSSAccessKeyId=LTAI5**************4G8qL&Signature=eTXOgbROSgExlW6J31RL%2F%2Fr7zk4%3D",
"subtask_status": "SUCCEEDED"
}],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 2,
"FAILED": 0
}
},
"usage": {
"duration": 7
}
}
返回参数说明
返回参数 | 类型 | 说明 |
task_id | string | 被查询任务的ID。 |
task_status | string | 被查询任务的状态。 |
file_url | string | 文件转写任务中所处理的文件URL。 |
transcription_url | string | 所处理文件的处理结果URL。 |
查询异步任务
查询异步任务,返回任务的状态和文件转写结果。异步任务的状态包括 PENDING 、 RUNNING 、 SUCCEEDED 、 FAILED 。本调用不会阻塞,将立即返回所查询任务的状态和结果。开发者可以编写代码,采用轮询的方式直到任务完成,再获取文件转写结果。
接口
dashscope.audio.asr.Transcription.fetch()
TranscriptionResult fetch(TranscriptionQueryParam param);
参数配置
参数 | 类型 | 默认值 | 说明 |
task | string | - | 在调用提交任务接口时所返回的 task_id 。 |
返回结果示例
PENDING/RUNNING状态
{
"status_code": 200,
"request_id": "04ea046b-ccca-4765-882c-9f60bd985150",
"code": null,
"message": "",
"output": {
"task_id": "bd725f8f-f699-4962-bcad-38a9fc2bcd7c",
"task_status": "RUNNING"
},
"usage": null
}
SUCCEEDED状态
{
"status_code": 200,
"request_id": "0411a162-f0df-9196-ba4e-7c4a03788bae",
"code": null,
"message": "",
"output": {
"task_id": "39bfce34-8744-4ee3-a85b-d42cc150908b",
"task_status": "SUCCEEDED",
"submit_time": "2023-10-23 17:41:03.403",
"scheduled_time": "2023-10-23 17:41:03.429",
"end_time": "2023-10-23 17:41:04.022",
"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/paraformer-v2/20231023/17%3A41/4adeaf61-aa36-4a16-81a1-db381d627f06-1.json?Expires=1698140464&OSSAccessKeyId=LTAI5**************4G8qL&Signature=QhsuSA0OCm%2BEBBmdRRF8K4xXP8Q%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/paraformer-v2/20231023/17%3A41/d9b23f85-55c1-43b9-a172-17a7afba3e40-1.json?Expires=1698140464&OSSAccessKeyId=LTAI5**************4G8qL&Signature=eTXOgbROSgExlW6J31RL%2F%2Fr7zk4%3D",
"subtask_status": "SUCCEEDED"
}],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 2,
"FAILED": 0
}
},
"usage": {
"duration": 7
}
}
返回参数说明
返回参数 | 类型 | 说明 |
task_id | string | 被查询任务的ID。 |
task_status | string | 被查询任务的状态。 |
file_url | string | 文件转写任务中所处理的文件URL。 |
transcription_url | string | 所处理文件的处理结果URL。 |
通过HTTP调用接口实现异步转写音视频文件
文件转写是异步任务,开发者可以通过HTTP提交接口提交任务,并且在循环中通过查询接口确认任务状态。在文件转写完成后获得语音识别结果。
Curl
提交任务
请将'{api-key}'替换为你的apikey。
curl -X POST \
-H 'Authorization: Bearer {api-key}' \
-H 'Content-Type: application/json' \
-H 'X-DashScope-Async: enable' \
-d '{"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],"language_hints":["zh", "en"]}}' \
https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
返回示例:
{
"output": {
"task_status": "PENDING",
"task_id": "c2e5d63b-96e1-4607-bb91-************"
},
"request_id": "77ae55ae-be17-97b8-9942--************""
}
查询任务
请将'{api-key}'替换为你的apikey,'{task_id}'为提交任务成功后获得的task_id。
curl -X POST -i 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' --header 'Authorization: Bearer {api-key}'
返回示例:
{
"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=LTAI5tQZd8AEcZX6KZV4****&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=LTAI5tQZd8AEcZX6KZV4****&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
"subtask_status": "SUCCEEDED"
}
],
"task_metrics": {
"TOTAL": 2,
"SUCCEEDED": 2,
"FAILED": 0
}
},
"usage": {
"duration": 9
}
}
返回结果请参考接口详情-等待异步任务结束
Python
import requests
import json
import time
api_key = "your-dashscope-api-key" # 在此处替换为您的API密钥
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,
},
}
# 录音文件转写服务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)
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。