AI 助理
备案控制台
文档
输入文档关键字查找
首页

录音文件识别API详情

更新时间：
产品详情
我的收藏

Paraformer语音识别

说明

支持的领域 / 任务：audio（音频） / asr（语音识别）

Paraformer语音识别提供的文件转写API，能够对常见的音频或音视频文件进行语音识别，并将结果返回给调用者。

常见的音频或音视频文件一般采用16kHz及以上的采样率进行录制，可选择paraformer-v1模型进行中英文语音识别，或选择paraformer-MTL-v1模型对超过20种语言及中文方言进行语音识别。当明确知道需要识别的语音是中英文时，选择paraformer-v1模型的准确率通常会比paraformer-MTL-v1模型更高。电话录音一般采用8kHz进行录制，对这类文件应选择paraformer-8k-v1模型进行语音识别以获得更佳的效果。

Paraformer语音识别返回较为丰富的结果供调用者选择使用，包括全文级文字、句子级文字、词和时间戳等。模型默认进行标点符号预测和逆文本正则化。

由于音视频文件的尺寸通常较大，文件传输和语音识别处理均需要时间，文件转写API通过异步调用方式来提交任务。开发者需要通过查询接口，在文件转写完成后获得语音识别结果。文件转写API支持批处理，用户可以单次上传最多100个文件URL，待所有URL转写完成后，用户可以一次性获取全部转写结果。

模型概览

模型名

模型简介

paraformer-v1

Paraformer中英文语音识别模型，支持16kHz及以上采样率的音频或视频语音识别。

paraformer-8k-v1

Paraformer中文语音识别模型，支持8kHz电话语音识别。

paraformer-mtl-v1

Paraformer多语言语音识别模型，支持16kHz及以上采样率的音频或视频语音识别。

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

API参考

前提条件

音视频文件转写

用以进行语音识别的具体模型通过 model 参数指定。需要进行语音识别的音视频文件通过 file_urls 参数指定，支持HTTP / HTTPS协议的URL。

说明

需要使用您的API-KEY替换示例中的 your-dashscope-api-key ，代码才能正常运行。

# For prerequisites running the following sample, visit https://help.aliyun.com/document_detail/611472.html

from http import HTTPStatus
import dashscope
import json
 
dashscope.api_key='your-dashscope-api-key'
 
task_response=dashscope.audio.asr.Transcription.async_call(
    model='paraformer-v1',
    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']
    )
 
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) {
    // 创建转写请求参数，需要用真实apikey替换your-dashscope-api-key
    TranscriptionParam param =
        TranscriptionParam.builder()
            .apiKey("your-dashscope-api-key")
            .model("paraformer-v1")
            .fileUrls(
                Collections.singletonList(
                    "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
            .build();
    try {
      Transcription transcription = new Transcription();
      // 提交转写请求
      TranscriptionResult result = transcription.asyncCall(param);
      // 等待转写完成
      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);
  }
}

文件转写API采用异步调用方式，开发者需谨慎处理任务提交、状态查询、获取结果的异步逻辑。

说明

文件转写服务对通过API提交的任务采取尽力服务原则进行处理。具体任务的排队等待时间取决于并发的队列长度和其它任务的文件时长，因而无法提供确切等待时间。通常情况下排队等待时间应小于数分钟。一旦结束排队进入处理状态，文件将被以数百倍的加速比进行语音识别。

API支持当前主流的音视频文件格式，包括：

支持的格式

aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv

重要

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

API支持通过 file_urls 参数指定最多100个文件URL进行转写。同时，对指定的文件存有大小方面的限制，具体为：

输入文件的方式

文件大小限制

通过URL指定

≤ 2GB

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

异步调用

以异步调用的方式向文件转写服务提交一个任务，返回被提交任务的信息。

  • 接口

dashscope.audio.asr.Transcribe.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。

phrase_id

（可选）

string

-

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

channel_id

（可选）

List[int]

[0]

指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如 [0] 代表对第一条音轨进行识别、 [0, 1] 代表对第一和第二条音轨分别进行识别等。

disfluency_removal_enabled

boolean

false

过滤语气词，默认关闭

  • 返回结果示例

{
    "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.Transcribe.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
	}
}

  • 返回参数说明

返回参数

类型

说明

code

int

源文件中音频的格式。

task_id

string

被查询任务的ID。

task_status

string

被查询任务的状态。

file_url

string

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

status

string

所处理文件的处理状态。

transcription_url

string

所处理文件的处理结果URL。

查询异步任务

查询异步任务，返回任务的状态和文件转写结果。异步任务的状态包括 PENDING 、 RUNNING 、 SUCCEEDED 、 FAILED 。本调用不会阻塞，将立即返回所查询任务的状态和结果。开发者可以编写代码，采用轮询的方式直到任务完成，再获取文件转写结果。

  • 接口

dashscope.audio.asr.Transcribe.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
	}
}

  • 返回参数说明

返回参数

类型

说明

code

int

源文件中音频的格式。

task_id

string

被查询任务的ID。

task_status

string

被查询任务的状态。

file_url

string

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

status

string

所处理文件的处理状态。

transcription_url

string

所处理文件的处理结果URL。

音视频文件转写结果文件

当一个文件转写任务成功后，通过wait()或fetch()调用可获取文件转写的结果。这个结果同样以文件的形式保存，其链接以 transcription_url 给出。开发者可以打开该URL以获取结果。

说明

异步任务文件转写结果文件URL的有效时间是24小时，从异步任务完成的时间开始计算。

  • 返回结果示例

{
	"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
	"properties": {
		"channels": [],
		"original_sampling_rate": 16000,
		"original_duration_in_milliseconds": 4726
	},
	"transcripts": [{
		"channel_id": 0,
		"content_duration_in_milliseconds": 3696,
		"text": "Hello, world, 这里是阿里巴巴语音实验室。",
		"sentences": [{
			"begin_time": 480,
			"end_time": 4176,
			"sentence_id": 0,
			"text": "Hello, world, 这里是阿里巴巴语音实验室。",
			"words": [{
					"begin_time": 480,
					"end_time": 860,
					"text": "Hello",
					"punctuation": ", "
				},
				{
					"begin_time": 860,
					"end_time": 1320,
					"text": "world",
					"punctuation": ", "
				},
				{
					"begin_time": 1320,
					"end_time": 2034,
					"text": "这里是",
					"punctuation": ""
				},
				{
					"begin_time": 2034,
					"end_time": 2986,
					"text": "阿里巴巴",
					"punctuation": ""
				},
				{
					"begin_time": 2986,
					"end_time": 3462,
					"text": "语音",
					"punctuation": ""
				},
				{
					"begin_time": 3462,
					"end_time": 4176,
					"text": "实验室",
					"punctuation": "。"
				}
			]
		}]
	}]
} {
	"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav",
	"properties": {
		"channels": [],
		"original_sampling_rate": 16000,
		"original_duration_in_milliseconds": 3834
	},
	"transcripts": [{
		"channel_id": 0,
		"content_duration_in_milliseconds": 2816,
		"text": "Hello, world, 这里是阿里巴巴语音实验室。",
		"sentences": [{
			"begin_time": 560,
			"end_time": 3376,
			"sentence_id": 0,
			"text": "Hello, world, 这里是阿里巴巴语音实验室。",
			"words": [{
					"begin_time": 560,
					"end_time": 880,
					"text": "Hello",
					"punctuation": ", "
				},
				{
					"begin_time": 880,
					"end_time": 1180,
					"text": "world",
					"punctuation": ", "
				},
				{
					"begin_time": 1180,
					"end_time": 1729,
					"text": "这里是",
					"punctuation": ""
				},
				{
					"begin_time": 1729,
					"end_time": 2461,
					"text": "阿里巴巴",
					"punctuation": ""
				},
				{
					"begin_time": 2461,
					"end_time": 2827,
					"text": "语音",
					"punctuation": ""
				},
				{
					"begin_time": 2827,
					"end_time": 3376,
					"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

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

状态码说明

DashScope通用状态码请查阅：返回状态码说明