录音文件识别API详情

前提条件

• 已开通服务并获得API-KEY：获取API-KEY、配置API-KEY到环境变量。

• 已安装最新版SDK：安装SDK。

音视频文件转写

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

# 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='sensevoice-v1',
    file_urls=['https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav'],
    language_hints=['en'],
    )
 
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.Arrays;
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("sensevoice-v1")
            .fileUrls(
                Arrays.asList(
                "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav"))
            .parameter("language_hints", new String[] {"en"})  			
            .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支持当前主流的音视频文件格式，包括：

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

API支持通过file_urls参数指定最多100个文件URL进行转写，且文件小于等于2 GB。

如果希望处理的文件超过了上述限制，可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践请参见最佳实践。

异步调用

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

• 接口

  • Java

    TranscriptionResult asyncCall(TranscriptionParam param);

  • Python

    dashscope.audio.asr.Transcription.async_call()

• 参数配置

  参数	类型	默认值	说明
  model	string	-	指定用于音视频文件转写的SenseVoice模型名，当前为sensevoice-v1。
  file_urls	List[string]	-	音视频文件转写的URL列表，支持HTTP/HTTPS协议，最多可支持100个文件URL。
  channel_id （可选）	List[int]	[0]	指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如[0]代表对第一条音轨进行识别、[0,1]代表对第一和第二条音轨分别进行识别等。
  disfluency_removal_enabled	boolean	false	过滤语气词，默认关闭。
  language_hints	list[str]	['auto‘]	指定识别语音中语言代码。sensevoice-v1模型只支持配置一个语种。默认使用“auto”自动检测语种。支持的语言代码参见支持语言列表。

• 返回结果示例

  {
      "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作为任务的全局唯一标识符将用于后续对任务状态的查询、结果获取等操作。

等待异步任务结束

• 接口

  • Java

    TranscriptionResult wait(TranscriptionQueryParam param);

  • Python

    dashscope.audio.asr.Transcription.wait()

• 参数配置

  参数	类型	默认值	说明
  task	string	-	在调用提交任务接口时所返回的task_id。

• 返回结果示例

  {
  	"status_code": 200,
  	"request_id": "0411a162-f0df-9196-ba4e-xxxxxxxxxxx",
  	"code": null,
  	"message": "",
  	"output": {
  		"task_id": "39bfce34-8744-4ee3-a85b-xxxxxxxxxxx",
  		"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。本调用不会阻塞，将立即返回所查询任务的状态和结果。开发者可以编写代码，采用轮询的方式直到任务完成，再获取文件转写结果。

• 接口

  • Java

    TranscriptionResult fetch(TranscriptionQueryParam param);

  • Python

    dashscope.audio.asr.Transcription.fetch()

• 参数配置

  参数	类型	默认值	说明
  task	string	-	在调用提交任务接口时所返回的task_id。

• 返回结果示例（PENDING、RUNNING状态）

  {
      "status_code": 200,
      "request_id": "04ea046b-ccca-4765-882c-xxxxxxxxxxx",
      "code": null,
      "message": "",
      "output": {
          "task_id": "bd725f8f-f699-4962-bcad-xxxxxxxxxxx",
          "task_status": "RUNNING"
      },
      "usage": null
  }

• 返回结果示例（SUCCEEDED状态）

  {
  	"status_code": 200,
  	"request_id": "0411a162-f0df-9196-ba4e-xxxxxxxxxxx",
  	"code": null,
  	"message": "",
  	"output": {
  		"task_id": "39bfce34-8744-4ee3-a85b-xxxxxxxxxxx",
  		"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以获取结果。

• 返回结果示例

  {
      "file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav",
      "properties": {
          "audio_format": "pcm_s16le",
          "channels": [
              0
          ],
          "original_sampling_rate": 16000,
          "original_duration_in_milliseconds": 17645
      },
      "transcripts": [
          {
              "channel_id": 0,
              "content_duration_in_milliseconds": 12710,
              "text": "<|Speech|> Senior staff, Principal Doris Jackson, Wakefield faculty, and of course, my fellow classmates. <|/Speech|> <|ANGRY|><|Speech|> I am honored to have been chosen to speak before my classmates, as well as the students across America today. <|/Speech|>",
              "sentences": [
                  {
                      "begin_time": 0,
                      "end_time": 7060,
                      "text": "<|Speech|> Senior staff, Principal Doris Jackson, Wakefield faculty, and of course, my fellow classmates. <|/Speech|> <|ANGRY|>"
                  },
                  {
                      "begin_time": 11980,
                      "end_time": 17630,
                      "text": "<|Speech|> I am honored to have been chosen to speak before my classmates, as well as the students across America today. <|/Speech|>"
                  }
              ]
          }
      ]
  }

• 返回参数说明

  返回参数	类型	说明
  audio_format	string	源文件中音频的格式。
  channels	List[int]	源文件中音频的音轨索引信息，对单轨音频返回[0]，对双轨音频返回[0,1]，以此类推。
  original_sampling_rate	int	源文件中音频的采样率（Hz）。
  original_duration_in_milliseconds	int	源文件中的原始音频时长（ms）。
  channel_id	int	表明转写结果的音轨索引，以0为起始。
  content_duration_in_milliseconds	int	音轨中被判定为语音内容的时长（ms）。 重要 SenseVoice语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写，并据此进行计量计费，非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的，可能与实际情况存在一定误差
  transcript	string	段落级别的语音转写结果。
  sentences	List[]	句子级别的语音转写结果。
  begin_time	int	开始时间戳（ms）。
  end_time	int	结束时间戳（ms）。
  text	string	语音转写结果。 如果语音中包含以下四种情绪：生气（ANGRY）、高兴（HAPPY）、伤心（SAD）和中性（NEUTRAL），以及四种常见的音频事件：掌声（Applause）、背景音乐（BGM）、笑声（Laughter）和说话声（Speech），则这些情绪和事件均会被检测到。