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

本文介绍FunASR录音文件识别RESTful API的参数和接口细节。

用户指南：关于模型介绍和选型建议请参见录音文件识别。

在线体验：暂不支持。

目前提供了提交任务接口和查询任务接口，通常情况下，您可以先调用提交任务接口上传识别任务，然后循环调用查询任务接口，直至任务完成。

前提条件

已开通服务并获取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通过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	`https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription`
请求方法	POST
请求头	`Authorization: Bearer {api-key} // 需替换为您自己的API Key Content-Type: application/json X-DashScope-Async: enable // 请勿遗漏该请求头，否则无法提交任务`
消息体	包含所有请求参数的消息体如下，对于可选字段，在实际业务中可根据需求省略： { "model":"fun-asr", //模型名，必选 "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":{ "vocabulary_id":"vocab-Xxxx", //热词ID，可选 "channel_id":[ 0 ], //音轨索引，可选 "special_word_filter": "xxx", //敏感词，可选 "diarization_enabled":false, //自动说话人分离，可选 "speaker_count": 2 //说话人数量参考，可选 } }

请求参数

点击查看请求示例

以下为调用提交任务接口的cURL示例：

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{"model":"fun-asr-v1","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]}}'

参数	类型	默认值	是否必须	说明
model	string	-	是	指定用于音视频文件转写的模型名。参见模型列表。
file_urls	array[string]	-	是	音视频文件转写的URL列表，支持HTTP / HTTPS协议，单次请求最多支持100个URL。
vocabulary_id	string	-	否	热词ID，此次语音识别中生效此热词ID对应的热词信息。默认不启用。使用方法请参考定制热词。
channel_id	array[integer]	[0]	否	指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如`[0]`表示仅识别第一条音轨，`[0, 1]`表示同时识别前两条音轨。
special_word_filter	string	-	否	指定在语音识别过程中需要处理的敏感词，并支持对不同敏感词设置不同的处理方式。若未传入该参数，系统将启用系统内置的敏感词过滤逻辑，识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的``。若传入该参数，则可实现以下敏感词处理策略：替换为 ``：将匹配的敏感词替换为等长的 ``；直接过滤：将匹配的敏感词从识别结果中完全移除。该参数的值应为一个 JSON 字符串，其结构如下所示： `{ "filter_with_signed": { "word_list": ["测试"] }, "filter_with_empty": { "word_list": ["开始", "发生"] }, "system_reserved_filter": true }` JSON字段说明： `filter_with_signed` 类型：对象。是否必填：否。描述：配置需替换为``的敏感词列表。识别结果中匹配的词语将被等长的 `` 替代。示例：以上述JSON为例，“帮我测试一下这段代码”的语音识别结果将会是“帮我一下这段代码”。内部字段： `word_list`: 字符串数组，列出需被替换的敏感词。 `filter_with_empty` 类型：对象。是否必填：否。描述：配置需从识别结果中移除（过滤）的敏感词列表。识别结果中匹配的词语将被完全删除。示例：以上述JSON为例，“比赛这就要开始了吗？”的语音识别结果将会是“比赛这就要了吗”。内部字段： `word_list`: 字符串数组，列出需被完全移除（过滤）的敏感词。 `system_reserved_filter` 类型：布尔值。是否必填：否。默认值：true。描述：是否启用系统预置的敏感词规则。设为`true`时，将同时启用系统内置的敏感词过滤逻辑，识别结果中与阿里云百炼敏感词表匹配的词语将被替换为等长的``。
diarization_enabled	boolean	false	否	自动说话人分离，默认关闭。仅适用于单声道音频，多声道音频不支持说话人分离。启用该功能后，识别结果中将显示`speaker_id`字段，用于区分不同说话人。有关`speaker_id`的示例，请参见识别结果说明。
speaker_count	integer	-	否	说话人数量参考值。取值范围为2至100的整数（包含2和100）。开启说话人分离功能后（diarization_enabled设置为true）生效。默认自动判断说话人数量，如果配置此项，只能辅助算法尽量输出指定人数，无法保证一定会输出此人数。

响应参数

点击查看响应示例

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

参数	类型	说明
task_status	string	任务状态。
task_id	string	任务ID。该ID在查询任务接口中作为请求参数传入。

查询任务接口

基本信息

接口描述	查询语音识别任务执行情况和结果。
URL	`https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}`
请求方法	POST
请求头	`Authorization: Bearer {api-key} // 需替换为您自己的API Key`
消息体	无。

请求参数

点击查看请求示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' --header "Authorization: Bearer $DASHSCOPE_API_KEY"

参数	类型	默认值	是否必须	说明
task_id	string	-	是	查询任务需指定其ID，该ID为提交任务接口被调用后返回的`task_id`。

响应参数

点击查看响应示例

当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为SUCCEEDED，需通过subtask_status字段判断具体子任务结果。

正常示例

{
  "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=yourOSSAccessKeyId&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=yourOSSAccessKeyId&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

异常示例

“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://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_id	string	被查询任务的ID。
task_status	string	被查询任务的状态。说明当任务包含多个子任务时，只要存在任一子任务成功，整个任务状态将标记为`SUCCEEDED`，需通过`subtask_status`字段判断具体子任务结果。
subtask_status	string	子任务状态。
file_url	string	文件转写任务中所处理的文件URL。
transcription_url	string	获取识别结果对应的链接。该链接有效期为24小时，超时后无法查询任务或通过先前查询结果中的URL下载结果。识别结果保存为JSON文件，您可以通过上述链接下载该文件或直接通过HTTP请求读取该文件中的内容。 JSON数据中各字段含义请参见识别结果说明。

识别结果说明

识别结果保存为JSON文件。

点击查看识别结果示例

{
    "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":3720,
            "text":"Hello world, 这里是阿里巴巴语音实验室。",
            "sentences":[
                {
                    "begin_time":100,
                    "end_time":3820,
                    "text":"Hello world, 这里是阿里巴巴语音实验室。",
                    "sentence_id":1,
                    "speaker_id":0, //当开启自动说话人分离功能时才会显示该字段
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // 这里省略其它内容
                    ]
                }
            ]
        }
    ]
}

需要关注的参数如下：

参数	类型	说明
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 time

api_key = "your-dashscope-api-key"  # 在此处替换为您的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": "fun-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）：

1、选择存储和托管方式

如以下这几种：

对象存储服务（推荐）：
- 使用云服务商的对象存储服务（如阿里云OSS），将音频文件上传到存储桶中，并设置为公开访问。
- 优点：高可用性、支持 CDN 加速、易于管理。
Web 服务器：
- 将音频文件放置在支持 HTTP/HTTPS 访问的 Web 服务器上（如 Nginx、Apache）。
- 优点：适合小型项目或本地测试。
内容分发网络（CDN）：
- 将音频文件托管在 CDN 上，通过 CDN 提供的 URL 访问。
- 优点：加速文件传输，适合高并发场景。

2、上传音频文件

根据选择的存储/托管方式，将音频上传，如：

对象存储服务：
- 登录云服务商的控制台，创建存储桶。
- 上传音频文件，并设置文件权限为“公共读”或生成临时访问链接。
Web 服务器：
- 将音频文件放置在服务器指定目录下（如 /var/www/html/audio/）。
- 确保文件可以通过 HTTP/HTTPS 访问。

3、生成公网可访问的URL

例如：

对象存储服务：
- 文件上传后，系统会自动生成一个公网访问 URL（通常格式为 https://<bucket-name>.<region>.aliyuncs.com/<file-name>）。
- 如果需要更友好的域名，可以绑定自定义域名并开启 HTTPS。
Web 服务器：
- 文件的访问 URL 通常是服务器地址加上文件路径（如 https://your-domain.com/audio/file.mp3）。
CDN：
- 配置 CDN 加速后，使用 CDN 提供的 URL（如 https://cdn.your-domain.com/audio/file.mp3）。

4、验证URL的可用性

公网环境下，确保生成的 URL 可以正常访问，例如：

在浏览器中打开 URL，检查是否能播放音频文件。
使用工具（如 curl 或 Postman）验证 URL 是否返回正确的 HTTP 响应（状态码 200）。

Q：多久能获取识别结果？

任务提交后将进入排队（PENDING）状态，排队时间取决于队列长度和文件时长，无法明确给出，通常在数分钟内，请耐心等待。并且音频时长越长，所需时间越久。

故障排查

如遇代码报错问题，请根据错误码中的信息进行排查。

Q：录音文件URL设置成OSS临时公网访问不通该如何处理？

headers中将X-DashScope-OssResourceResolve设为enable。

不推荐该方式。

Java SDK或者Python SDK不支持对headers进行配置。

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