本文介绍FunAudio-ASR录音文件识别RESTful API的参数和接口细节。
用户指南：关于模型介绍和选型建议请参见录音文件识别-Paraformer/Fun-ASR/Gummy/SenseVoice。
在线体验：暂不支持。
目前提供了提交任务接口和查询任务接口，通常情况下，您可以先调用提交任务接口上传识别任务，然后循环调用查询任务接口，直至任务完成。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量，而非硬编码在代码中，防范因代码泄露导致的安全风险。
说明当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时鉴权Token。
与长期有效的 API Key 相比，临时鉴权 Token 具备时效性短（60秒）、安全性高的特点，适用于临时调用场景，能有效降低API Key泄露的风险。
使用方式：在代码中，将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。
在阿里云百炼控制台的Fun-ASR模型列表页面，点击操作列的立即申请按钮提交申请，审核通过后方可使用。
模型列表
模型名称 | 版本 | 单价 | 免费额度 |
fun-asr 当前等同fun-asr-2025-08-25 | 稳定版 | 0.00022元/秒 | 36,000秒（10小时） 该模型开放邀测（所有人可见，申请使用），申请通过后发放免费额度 有效期90天 |
fun-asr-2025-08-25 | 快照版 |
约束
服务不支持本地音视频文件直传（也不支持base64格式音频），输入源需为可通过公网访问的文件URL（支持HTTP/HTTPS协议，示例：https://your-domain.com/file.mp3）。
URL通过file_urls参数指定，单次请求最多支持100个URL。
音频格式
aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv重要由于音视频格式及其变种众多，技术上无法穷尽测试，API不能保证所有格式均能够被正确识别。请通过测试验证您所提供的文件能够获得正常的语音识别结果。
音频采样率：任意
音频文件大小和时长
音频文件不超过2GB；时长在12小时以内。
如果希望处理的文件超过了上述限制，可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率（针对录音文件识别场景）。
批处理音频数目
单次请求最多支持100个文件URL。
可识别语言：中文、英文
接口调用方式限制
不支持前端直接调用API，需通过后端中转。
提交任务接口
基本信息
接口描述 | 提交语音识别任务。 |
URL | |
请求方法 | POST |
请求头 | |
消息体 | 包含所有请求参数的消息体如下，对于可选字段，在实际业务中可根据需求省略： |
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 指定用于音视频文件转写的模型名。参见模型列表。 |
file_urls | array[string] | - | 是 | 音视频文件转写的URL列表，支持HTTP / HTTPS协议，单次请求最多支持100个URL。 |
vocabulary_id | string | - | 否 | 热词ID，此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。 |
channel_id | array[integer] | [0] | 否 | 指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如 |
special_word_filter | string | - | 否 | 指定在语音识别过程中需要处理的敏感词，并支持对不同敏感词设置不同的处理方式。 若未传入该参数，系统将启用系统内置的敏感词过滤逻辑，识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的 若传入该参数，则可实现以下敏感词处理策略：
该参数的值应为一个 JSON 字符串，其结构如下所示： JSON字段说明：
|
diarization_enabled | boolean | false | 否 | 自动说话人分离，默认关闭。 仅适用于单声道音频，多声道音频不支持说话人分离。 启用该功能后，识别结果中将显示 有关 |
speaker_count | integer | - | 否 | 说话人数量参考值。取值范围为2至100的整数（包含2和100）。 开启说话人分离功能后（diarization_enabled设置为true）生效。 默认自动判断说话人数量，如果配置此项，只能辅助算法尽量输出指定人数，无法保证一定会输出此人数。 |
响应参数
参数 | 类型 | 说明 |
task_status | string | 任务状态。 |
task_id | string |
查询任务接口
基本信息
接口描述 | 查询语音识别任务执行情况和结果。 |
URL | |
请求方法 | POST |
请求头 | |
消息体 | 无。 |
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
task_id | string | - | 是 | 查询任务需指定其ID，该ID为提交任务接口被调用后返回的 |
响应参数
参数 | 类型 | 说明 |
task_id | string | 被查询任务的ID。 |
task_status | string | 被查询任务的状态。 说明 当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为 |
subtask_status | string | 子任务状态。 |
file_url | string | 文件转写任务中所处理的文件URL。 |
transcription_url | string | 获取识别结果对应的链接。该链接有效期为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 | 预测出的词之后的标点符号（如有）。 |
其他接口：批量查询任务状态/取消任务
详情请参见管理异步任务：支持批量查询24小时内提交的录音文件识别任务，同时支持取消PENDING（排队）状态的任务。
完整示例
您可以使用编程语言自带的HTTP类库，来实现提交和查询任务的请求：先调用提交任务接口上传识别任务，然后循环调用查询任务接口，直至任务完成。
以Python为例，代码如下：
import requests
import json
import os
import time
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key = "sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
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",
]
# 提交文件转写任务，包含待转写文件url列表
def submit_task(apikey, file_urls) -> str:
headers = {
"Authorization": f"Bearer {apikey}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
data = {
"model": "funaudio-asr",
"input": {"file_urls": file_urls},
"parameters": {
"channel_id": [0],
"vocabulary_id": "vocab-Xxxx",
},
}
# 录音文件转写服务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)错误码
如遇报错问题，请参见错误信息进行排查。
当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为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：录音文件URL设置成OSS临时公网访问不通该如何处理？
headers中将X-DashScope-OssResourceResolve设为enable。
不推荐该方式。
Java SDK或者Python SDK不支持对headers进行配置。
Q：一直轮询不到结果？
可能是限流原因，请耐心等待。
Q：无法识别语音（无识别结果）是什么原因？
请检查音频格式和采样率是否正确且符合参数约束。
可以使用ffprobe工具获取音频的容器、编码、采样率、声道等信息：
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx