本文介绍FunASR录音文件识别Java SDK的参数和接口细节。
用户指南:关于模型介绍和选型建议请参见录音文件识别。
在线体验:暂不支持。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
说明当您需要为第三方应用或用户提供临时访问权限,或者希望严格控制敏感数据访问、删除等高风险操作时,建议使用临时鉴权Token。
与长期有效的 API Key 相比,临时鉴权 Token 具备时效性短(60秒)、安全性高的特点,适用于临时调用场景,能有效降低API Key泄露的风险。
使用方式:在代码中,将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。
在阿里云百炼控制台的FunASR模型列表页面,点击操作列的立即申请按钮提交申请,审核通过后方可使用。
模型与价格
模型名称 | 版本 | 单价 | 免费额度 |
fun-asr 当前等同fun-asr-2025-08-25 | 稳定版 | 0.00022元/秒 | 36,000秒(10小时) 该模型开放邀测(所有人可见,申请使用),申请通过后发放免费额度 有效期180天 |
fun-asr-2025-08-25 | 快照版 |
约束
服务不支持本地音视频文件直传(也不支持base64格式音频),输入源需为可通过公网访问的文件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;时长在12小时以内。
如果希望处理的文件超过了上述限制,可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率(针对录音文件识别场景)。
批处理音频数目
单次请求最多支持100个文件URL。
可识别语言:中文、英文
快速开始
核心类(Transcription)提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行录音文件识别:
异步提交任务+同步等待任务结束:提交任务后,阻塞当前线程直到任务结束并获取识别结果。
异步提交任务+异步查询任务执行结果:提交任务后,在需要的时候通过调用查询任务接口获取任务的执行结果。
异步提交任务+同步等待任务结束
配置请求参数。
调用核心类(Transcription)的
asyncCall
方法异步提交任务。说明文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING
)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
调用核心类(Transcription)的
wait
方法同步等待任务结束。任务的状态包括
PENDING
、RUNNING
、SUCCEEDED
和FAILED
。当任务处于PENDING
或RUNNING
状态时,wait
接口将被阻塞。当任务处于SUCCEEDED
或FAILED
状态时,wait
接口不再阻塞并返回任务的执行结果。wait
返回任务执行结果(TranscriptionResult)。
异步提交任务+异步查询任务执行结果
配置请求参数。
调用核心类(Transcription)的
asyncCall
方法异步提交任务。说明文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING
)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
循环调用核心类(Transcription)的
fetch
方法直到获取最终的任务结果。当任务状态为
SUCCEEDED
或FAILED
时,停止轮询并处理结果。fetch
返回任务执行结果(TranscriptionResult)。
请求参数
请求参数通过TranscriptionParam
的链式方法进行配置。
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | String | - | 是 | 指定用于音视频文件转写的模型名。参见模型与价格。 |
fileUrls | List<String> | - | 是 | 音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求最多支持100个URL。 |
vocabularyId | String | - | 否 | 热词ID,此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。 |
channelId | List<Integer> | [0] | 否 | 指定在多音轨文件中需要进行语音识别的音轨索引,以List的形式给出,例如 |
specialWordFilter | String | - | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。 若未传入该参数,系统将启用系统内置的敏感词过滤逻辑,识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的 若传入该参数,则可实现以下敏感词处理策略:
该参数的值应为一个 JSON 字符串,其结构如下所示:
JSON字段说明:
|
diarizationEnabled | Boolean | false | 否 | 自动说话人分离,默认关闭。 仅适用于单声道音频,多声道音频不支持说话人分离。 启用该功能后,识别结果中将显示 有关 |
speakerCount | Integer | - | 否 | 说话人数量参考值。取值范围为2至100的整数(包含2和100)。 开启说话人分离功能后( 默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。 |
apiKey | String | - | 否 | 用户API Key。如已将API Key配置到环境变量,则无须在代码中设置。否则一定要在代码中进行设置。 |
响应结果
任务执行结果(TranscriptionResult
)
TranscriptionResult
封装了当前任务执行结果。
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | requestId | 获取requestId。 |
| 无 | taskId | 获取taskId。 |
| 无 |
| 获取任务状态。
说明 当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 |
| 无 | 获取子任务执行结果(TranscriptionTaskResult)。 每个任务对一个或多个音频文件进行识别,不同音频文件在不同的子任务中处理,因此每个任务对应一到多个子任务。 | |
| 无 | 任务执行结果,为JSON格式的数据 | 获取任务执行结果。 该结果是一个JSON格式的数据,如果您想通过 |
子任务执行结果(TranscriptionTaskResult
)
TranscriptionTaskResult
封装了子任务执行结果。子任务对单个音频文件进行识别。
接口/方法 | 参数 | 返回值 | 描述 |
| 无 | 被识别的音频文件的链接 | 获取被识别音频文件的链接。 |
| 无 | 识别结果对应的链接 | 获取识别结果对应的链接。该链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。 识别结果保存为JSON文件,您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。 JSON数据中各字段含义请参见识别结果说明。 |
| 无 |
| 获取子任务状态。
|
| 无 | 任务执行过程中关键信息,可能为空 | 获取任务执行过程中的关键信息。 当任务失败时,可查看该内容分析原因。 |
识别结果说明
识别结果保存为JSON文件。
需要关注的参数如下:
参数 | 类型 | 说明 |
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 | integer | 音轨中被判定为语音内容的时长(ms)。 重要 语音识别模型服务仅对音轨中被判定为语音内容的时长进行语音转写,并据此进行计量计费,非语音内容不计量、不计费。通常情况下语音内容时长会短于原始音频时长。由于对是否存在语音内容的判定是由AI模型给出的,可能与实际情况存在一定误差。 |
transcript | string | 段落级别的语音转写结果。 |
sentences | array | 句子级别的语音转写结果。 |
words | array | 词级别的语音转写结果。 |
begin_time | integer | 开始时间戳(ms)。 |
end_time | integer | 结束时间戳(ms)。 |
text | string | 语音转写结果。 |
speaker_id | integer | 当前说话人的索引,以0为起始,用于区分不同的说话人。 仅在启用说话人分离功能时,该字段才会显示于识别结果中。 |
punctuation | string | 预测出的词之后的标点符号(如有)。 |
关键接口
任务查询参数配置类(TranscriptionQueryParam
)
TranscriptionQueryParam
在等待任务完成(调用Transcription
的wait
方法)或查询任务执行结果(调用Transcription
的fetch
方法)时用到。
通过静态方法FromTranscriptionParam
创建TranscriptionQueryParam
实例。
接口/方法 | 参数 | 返回值 | 描述 |
|
|
| 创建 |
核心类(Transcription
)
Transcription
可以通过“import com.alibaba.dashscope.audio.asr.transcription.*;
”方式引入。它的关键接口如下:
接口/方法 | 参数 | 返回值 | 描述 |
|
| 异步提交语音识别任务。 | |
|
| 阻塞当前线程直到异步任务结束(任务状态为 | |
|
| 异步查询当前任务执行结果。 |
其他接口:批量查询任务状态/取消任务
详情请参见管理异步任务:支持批量查询24小时内提交的录音文件识别任务,同时支持取消PENDING
(排队)状态的任务。
错误码
如遇报错问题,请参见错误信息进行排查。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为SUCCEEDED
,需通过subtask_status
字段判断具体子任务结果。
错误返回示例:
{
"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
}
}
常见问题
功能特性
Q:是否支持Base64编码方式的音频?
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
Q:如何将音频文件以公网可访问的URL形式提供?
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
Q:多久能获取识别结果?
任务提交后将进入排队(PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内,请耐心等待。并且音频时长越长,所需时间越久。
故障排查
如遇代码报错问题,请根据错误码中的信息进行排查。
Q:一直轮询不到结果?
可能是限流原因,请耐心等待。
Q:无法识别语音(无识别结果)是什么原因?
请检查请求参数中的音频格式(format
)和采样率(sampleRate
/sample_rate
)设置是否正确且符合参数约束。以下为常见错误示例:
音频文件扩展名为 .wav,但实际为 MP3 格式,而请求参数
format
设置为 mp3(参数设置错误)。音频采样率为 3600Hz,但请求参数
sampleRate
/sample_rate
设置为 48000(参数设置错误)。
可以使用ffprobe工具获取音频的容器、编码、采样率、声道等信息:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx