paraformer录音文件识别API详情

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支持当前主流的音视频文件格式,包括:aacamraviflacflvm4amkvmovmp3mp4mpegoggopuswavwebmwmawmv

    重要

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

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

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

    • 每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。

# 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小时,从异步任务完成的时间开始计算。

异步调用

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

接口

以下代码片段展示了如何创建一个使用paraformer-v2模型,配置热词和语种等请求参数进行异步调用:

# Submit the transcription task
task_response = dashscope.audio.asr.Transcription.async_call(
    model='paraformer-v2',
    language_hints=['zh', 'en'],
    vocabulary_id='vocab-Xxxx',
    speaker_count=1,
    diarization_enabled=True,
    file_urls=[
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav',
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/sample_video_poetry.mp4',
        'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3'
    ])
TranscriptionParam param =
        TranscriptionParam.builder()
                .apiKey("sk-3b184157bef946c6aa7d950b5916325f")
                .model("paraformer-v2")
                .parameter("language_hints", new String[] {"en"})
                .vocabularyId("vocab-Xxxx")
                .speakerCount(1)
                .diarizationEnabled(true)
                .fileUrls(
                        Arrays.asList(
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav",
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/sample_video_poetry.mp4",
                                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3"))
                .build();

Transcription transcription = new Transcription();
// 提交转写请求
TranscriptionResult result = transcription.asyncCall(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

过滤语气词,默认关闭

timestamp_alignment_enabled

boolean

false

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

special_word_filter

string

-

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

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

具体调用说明请见下文的敏感词调用示例。

说明

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

language_hints

List[str]

['zh', 'en']

指定识别语音中语言的代码列表。支持的语言代码:

  • zh: 中文

  • en: 英文

  • ja: 日语

  • yue: 粤语

  • ko: 韩语

注:仅对paraformer-v2生效。在java SDK中,此参数需要通过parameter额外参数配置,用法请参考快速开始中示例代码。

diarization_enabled

bool

false

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

speaker_count

int

-

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

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

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

敏感词调用示例

敏感词的输入为一个JSON格式字符串,示例如下:

{
    "system_reserved_filter": true,
    "filter_with_empty": {
        "word_list": [
            "开始",
            "发生"
        ]
    },
    "filter_with_signed": {
        "word_list": [
            "测试"
        ]
    }
}

其中,system_reserved_filter开关打开后会使用默认敏感词表。filter_with_empty中的词会在识别结果中被替换为空,filter_with_signed中的词会在识别结果中被替换为"*"。

返回结果示例
{
    "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)

任务失败

当录音文件识别任务失败时会返回报错信息。您可以通过报错信息和错误码定位出错原因并处理。

错误返回示例

{
    "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_status 就会显示SUCCEEDED,请您查看每一个任务的 subtask_status 和 message 判断任务的状态。

语音相关错误码

错误码(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小时。

建议将音频进行切分,分多次提交识别任务,可以参考文档

DECODER_ERROR

检测音频文件信息失败。

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

INTERNAL_ERROR

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

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

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