SenseVoice录音文件识别Java API_大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文介绍SenseVoice录音文件识别Java API的使用。

前提条件

已开通服务并获取API Key。请配置API Key到环境变量，而非硬编码在代码中，防范因代码泄露导致的安全风险。
安装最新版DashScope SDK。

模型列表

模型名	模型简介
sensevoice-v1	语音识别大模型，支持50多种语言的识别，具备情感分析和音频事件检测功能，并默认提供标点符号预测及逆文本正则化（ITN）能力。

约束

服务不支持本地音/视频文件直传，输入源需为可通过公网访问的文件URL（支持HTTP/HTTPS协议，示例：https://your-domain.com/file.mp3）。URL通过fileUrls参数指定，单次请求最多支持100个URL。

音频格式
aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv
重要
由于音/视频格式及其变种众多，技术上无法穷尽测试，API不能保证所有格式均能够被正确识别。请通过测试验证您所提供的文件能够获得正常的语音识别结果。
音频文件大小和时长
音频文件不超过2GB；无时长限制。
如果希望处理的文件超过了上述限制，可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率。
批处理音频数目
单次请求最多支持100个文件URL。

可识别语言
详情请参见语言列表。
重要
SenseVoice每次只支持识别一种语言，请勿在language_hints参数中指定多个语言代码。

调用模式

核心类（Transcription）提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用模式进行录音文件识别：

异步提交任务+同步等待任务结束：提交任务后，阻塞当前线程直到任务结束并获取识别结果。
异步提交任务+异步查询任务执行结果：提交任务后，在需要的时候通过调用查询任务接口获取任务的执行结果。

异步提交任务+同步等待任务结束

配置请求参数。
实例化核心类（Transcription）。
调用核心类（Transcription）的asyncCall方法异步提交任务。
说明
- 语音识别服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内。任务开始处理后，语音识别将以数百倍加速完成。
- 每一个任务完成后，识别结果和URL下载链接有效期为24小时，超时后无法获取任务状态或通过原有URL下载结果。
循环调用核心类（Transcription）的wait方法同步等待任务结束。
任务的状态包括PENDING、RUNNING、SUCCEEDED和FAILED。当任务处于PENDING或RUNNING状态时，wait接口将被阻塞。当任务处于SUCCEEDED或FAILED状态时，wait接口不再阻塞并返回任务的执行结果。
wait返回任务执行结果（TranscriptionResult）。

点击查看完整示例

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.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // 若未配置环境变量，取消下一行的注释并将your-api-key替换成您自己的API Key
                        // .apiKey("your-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();
                // 获取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);
    }
}

异步提交任务+异步查询任务执行结果

配置请求参数。
实例化核心类（Transcription）。
调用核心类（Transcription）的asyncCall方法异步提交任务。
说明
- 语音识别服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内。任务开始处理后，语音识别将以数百倍加速完成。
- 每一个任务完成后，识别结果和URL下载链接有效期为24小时，超时后无法获取任务状态或通过原有URL下载结果。
调用核心类（Transcription）的fetch方法直到获取最终的任务结果。
当任务状态为SUCCEEDED或FAILED时，停止轮询并处理结果。
fetch返回任务执行结果（TranscriptionResult）。

点击查看完整示例

import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.common.TaskStatus;
import com.google.gson.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.*;
import java.net.HttpURLConnection;
import java.util.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        TranscriptionParam param =
                TranscriptionParam.builder()
                        // 若未配置环境变量，取消下一行的注释并将your-api-key替换成您自己的API Key
                        // .apiKey("your-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);
            System.out.println("RequestId: " + result.getRequestId());
            // 循环获取任务执行结果，直到任务结束
            while (true) {
                result = transcription.fetch(TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
                if (result.getTaskStatus() == TaskStatus.SUCCEEDED || result.getTaskStatus() == TaskStatus.FAILED) {
                    break;
                }
                Thread.sleep(1000);
            }

            // 获取语音识别结果
            List<TranscriptionTaskResult> taskResultList = result.getResults();
            if (taskResultList != null && taskResultList.size() > 0) {
                TranscriptionTaskResult taskResult = taskResultList.get(0);
                // 获取识别结果的url
                String transcriptionUrl = taskResult.getTranscriptionUrl();
                // 获取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);
    }
}

请求参数

请求参数通过TranscriptionParam的链式方法进行配置。

点击查看示例

TranscriptionParam param =
                TranscriptionParam.builder()
                        .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();

参数	类型	默认值	是否必须	说明
model	String	-	是	指定模型名。固定为`sensevoice-v1`。
fileUrls	List<String>	-	是	待识别音/视频文件的URL列表，支持HTTP / HTTPS协议，单次请求最多支持100个URL。
channelId	List<Integer>	[0]	否	指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如`[0]`表示仅识别第一条音轨，`[0, 1]`表示同时识别前两条音轨。
disfluencyRemovalEnabled	Boolean	FALSE	否	过滤语气词，默认关闭。
language_hints	String[]	["auto"]	否	指定识别语音中语言代码。默认使用“auto”自动检测语种。支持的语言代码请参见语言列表。 `language_hints`只支持指定一个语言代码。说明 `language_hints`需要通过`TranscriptionParam`实例的`parameter`方法或者`parameters`方法进行设置：通过parameter设置 `TranscriptionParam param = TranscriptionParam.builder() .parameter("language_hints", new String[]{"en"}) .build();` 通过parameters设置 `RecognitionParam param = RecognitionParam.builder() .parameters(Map.of( "language_hints", new String[]{"en"} )) .build();`
apiKey	String	-	否	用户API Key。如已将API Key配置到环境变量，则无须在代码中设置。

响应结果

任务执行结果（`TranscriptionResult`）

TranscriptionResult封装了当前任务执行结果。

接口/方法	参数	返回值	描述
`public String getRequestId()`	无	requestId	获取requestId。
`public String getTaskId()`	无	taskId	获取taskId。
`public TaskStatus getTaskStatus()`	无	`TaskStatus`，任务状态	获取任务状态。 `TaskStatus`为枚举类，只需关注`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`这四个状态即可。说明当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为`SUCCEEDED`，需通过`subtask_status`字段判断具体子任务结果。
`public List<TranscriptionTaskResult> getResults()`	无	子任务执行结果（TranscriptionTaskResult）	获取子任务执行结果。每个任务对一个或多个音频文件进行识别，不同音频文件在不同的子任务中处理，因此每个任务对应一到多个子任务。
`public JsonObject getOutput()`	无	任务执行结果，为JSON格式的数据	获取任务执行结果。该结果是一个JSON格式的数据，如果您想通过`getOutput`接口获取任务执行结果，请您在获取结果后自行解析。点击查看JSON示例正常示例 `{ "task_id":"0795ff8c-b666-4e91-bb8b-xxx", "task_status":"SUCCEEDED", "submit_time":"2025-02-13 16:12:09.109", "scheduled_time":"2025-02-13 16:12:09.128", "end_time":"2025-02-13 16:12:10.189", "results":[ { "file_url":"https://xxx1.wav", "transcription_url":"https://xxx1.json", "subtask_status":"SUCCEEDED" }, { "file_url":"https://xxx2.wav", "transcription_url":"https://xxx2.json", "subtask_status":"SUCCEEDED" } ], "task_metrics":{ "TOTAL":2, "SUCCEEDED":2, "FAILED":0 } }` 异常示例 “`code`”为错误码，“`message`”为错误信息，只有异常情况才有这两个字段，您可以通过这两个字段，对照错误码排查问题。 { "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://xxx1.wav", "transcription_url":"https://xxx1.json", "subtask_status":"SUCCEEDED" }, { "file_url":"https://xxx2.wav", "code": "InvalidFile.DownloadFailed", "message": "The audio file cannot be downloaded.", "subtask_status": "FAILED" } ], "task_metrics": { "TOTAL": 2, "SUCCEEDED": 1, "FAILED": 1 } }

子任务执行结果（`TranscriptionTaskResult`）

TranscriptionTaskResult封装了子任务执行结果。子任务对单个音频文件进行识别。

接口/方法	参数	返回值	描述
`public String getFileUrl()`	无	被识别的音频文件的链接	获取被识别音频文件的链接。
`public String getTranscriptionUrl()`	无	识别结果对应的链接	获取识别结果对应的链接。该链接有效期为24小时，超时后无法查询任务或通过先前查询结果中的URL下载结果。识别结果保存为JSON文件，您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。 JSON数据中各字段含义请参见识别结果说明。
`public TaskStatus getSubTaskStatus()`	无	`TaskStatus`，子任务状态	获取子任务状态。 `TaskStatus`为枚举类，只需关注`PENDING`、`RUNNING`、`SUCCEEDED`和`FAILED`这四个状态即可。
`public String getMessage()`	无	任务执行过程中关键信息，可能为空	获取任务执行过程中的关键信息。当任务失败时，可查看该内容分析原因。

识别结果说明

识别结果保存为JSON文件。

点击查看识别结果示例

{
  "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": 13240,
      "text": "\u003c|Speech|\u003e Senior staff, principal doris jackson, wakefield faculty, and of course, my fellow classmates. \u003c|/Speech|\u003e \u003c|NEUTRAL|\u003e\u003c|Applause|\u003e \u003c|Speech|\u003e I am honored \u003c|/Applause|\u003e to have been chosen to speak before my classmates, as well as the students across America today. \u003c|/Speech|\u003e",
      "sentences": [
        {
          "begin_time": 0,
          "end_time": 7480,
          "text": "\u003c|Speech|\u003e Senior staff, principal doris jackson, wakefield faculty, and of course, my fellow classmates. \u003c|/Speech|\u003e \u003c|NEUTRAL|\u003e"
        },
        {
          "begin_time": 11880,
          "end_time": 17640,
          "text": "\u003c|Applause|\u003e \u003c|Speech|\u003e I am honored \u003c|/Applause|\u003e to have been chosen to speak before my classmates, as well as the students across America today. \u003c|/Speech|\u003e"
        }
      ]
    }
  ]
}

需要关注的参数如下：

参数	类型	说明
audio_format	string	源文件中音频的格式。
channels	array[integer]	源文件中音频的音轨索引信息，对单轨音频返回[0]，对双轨音频返回[0, 1]，以此类推。
original_sampling_rate	integer	源文件中音频的采样率（Hz）。
original_duration_in_milliseconds	integer	源文件中的原始音频时长（ms）。
channel_id	integer	识别结果的音轨索引，以0为起始。
content_duration_in_milliseconds	integer	音轨中被判定为语音内容的时长（ms）。重要 SenseVoice服务根据音频中AI识别出的有效语音时长计费，非语音段落（如静默、背景音）不计费。由于技术限制，系统判定的语音时段可能与实际存在细微差异，计费结果以服务端数据为准。
transcript	string	段落级别的语音识别结果。
sentences	array	句子级别的语音识别结果。
begin_time	integer	开始时间戳（ms）。
end_time	integer	结束时间戳（ms）。
text	string	语音识别结果。说明支持4种情绪的情感识别：生气（ANGRY）、高兴（HAPPY）、伤心（SAD）和中性（NEUTRAL）。若识别结果中未出现上述情感，或返回结果中包含“`\|SPECIAL_TOKEN_1\|`”，代表该语音中未检测到特定情绪。情感一般出现在识别结果最末端，例如：“`今天天气好棒啊！\|HAPPY\|`”。音频事件检测：支持4种常见音频事件识别，包括掌声（Applause）、背景音乐（BGM）、笑声（Laughter）和人声（Speech）。音频事件通过起始符（格式为“`\|事件类型\|`”，例如“`\|Applause\|`”）和结束符（格式为“`\|/事件类型\|`”，例如“`\|/Applause\|`”）标记。例如：“`\|Applause\|今天\|/Applause\|天气好棒啊！`”表示在说“今天”这两个字的时候有掌声存在。

关键接口

任务查询参数配置类（`TranscriptionQueryParam`）

TranscriptionQueryParam在等待任务完成（调用Transcription的wait方法）或查询任务执行结果（调用Transcription的fetch方法）时用到。

通过静态方法FromTranscriptionParam创建TranscriptionQueryParam实例。

点击查看示例

// 创建请求参数
TranscriptionParam param =
                TranscriptionParam.builder()
                        // 若未配置环境变量，取消下一行的注释并将your-api-key替换成您自己的API Key
                        // .apiKey("your-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();

TranscriptionQueryParam queryParam = TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId());

接口/方法	参数	返回值	描述
`public static TranscriptionQueryParam FromTranscriptionParam(TranscriptionParam param, String taskId)`	`param`：`TranscriptionParam`实例 `taskId`：任务ID	`TranscriptionQueryParam`实例	创建`TranscriptionQueryParam`实例。

核心类（`Transcription`）

Transcription可以通过“import com.alibaba.dashscope.audio.asr.transcription.*;”方式引入。它的关键接口如下：

接口/方法	参数	返回值	描述
`public TranscriptionResult asyncCall(TranscriptionParam param)`	`param`：语音识别相关参数，`TranscriptionParam`实例	任务执行结果（TranscriptionResult）	异步提交语音识别任务。
`public TranscriptionResult wait(TranscriptionQueryParam queryParam)`	`queryParam`：`TranscriptionQueryParam`实例	任务执行结果（TranscriptionResult）	阻塞当前线程直到异步任务结束（任务状态为`SUCCEEDED`或`FAILED`）。
`public TranscriptionResult fetch(TranscriptionQueryParam queryParam)`	`queryParam`：`TranscriptionQueryParam`实例	任务执行结果（TranscriptionResult）	异步查询当前任务执行结果。

错误码

错误代码 Code	错误信息Message（具体信息内容可能跟随场景有所变化）	含义说明
InvalidFile.DecodeFailed	The audio file cannot be decoded.	无法解码文件。请检查文件编码是否正确，并确认文件为正确的音频格式。

更多百炼平台相关错误码请参见错误信息。

常见问题

请参见GitHub QA。

语言列表

Sensevoice支持如下50多种语言，其中top10为重点支持语言。可通过查询下表获取语言代码并配置language_hints参数以获得更佳的效果，默认支持中文和英文。

语言		语言代码
重点语言	中文（Chinese）	zh
	英文（English）	en
	粤语（Cantonese）	yue
	日语（Japanese）	ja
	韩语（Korean）	ko
	俄语（Russian）	ru
	法语（French）	fr
	意大利语（Italian）	it
	德语（German）	de
	西班牙语（Spanish）	es
更多语言	加泰罗尼亚语（Catalan）	ca
	印度尼西亚语（Indonesian）	id
	泰语（Thai）	th
	荷兰语（Dutch）	nl
	葡萄牙语（Portuguese）	pt
	捷克语（Czech）	cs
	波兰语（Polish）	pl
	希腊语（Greek）	el
	马来语（Malay）	ms
	塔加洛语（Tagalog）	tl
	保加利亚语（Bulgarian）	bg
	克罗地亚语（Croatian）	hr
	丹麦语（Danish）	da
	土耳其语（Turkish）	tr
	越南语（Vietnamese）	vi
	希伯来语（Hebrew ）	he
	匈牙利语（Hungarian）	hu
	乌克兰语（Ukrainian）	uk
	爪哇语（Javanese）	jw
	乌兹别克语（Uzbek）	uz
	挪威（Norwegian）	no
	罗马尼亚（Romanian）	ro
	瑞典语（Swedish）	sv
	波斯语（Persian）	fa
	泰米尔语（Tamil）	ta
	阿塞拜疆语（Azerbaijani）	az
	孟加拉语（Bengali）	bn
	缅甸语（Myanmar）	my
	高棉语（Khmer ）	km
	印地语（Hindi）	hi
	卡纳达语（Kannada ）	kn
	老挝语（Lao）	lo
	马拉雅拉姆语（Malayalam）	ml
	马拉地语（Marathi）	mr
	蒙古语（Mongolian）	mn
	尼泊尔语（Nepali）	ne
	旁遮普语（Punjabi ）	pa
	僧伽罗语（Sinhala）	si
	斯瓦希里语（Swahili）	sw
	泰卢固语（Telugu）	te
	乌尔都语（Urdu）	ur
	豪萨语（Hausa）	ha

前提条件

模型列表

约束

调用模式

异步提交任务+同步等待任务结束

异步提交任务+异步查询任务执行结果

请求参数

通过parameter设置

通过parameters设置

响应结果

任务执行结果（TranscriptionResult）

子任务执行结果（TranscriptionTaskResult）