Fun-ASR录音文件识别Python SDK使用文档

一、概述

本文详细介绍Fun-ASR录音文件识别Python SDK的参数配置、接口调用、使用约束及常见问题，帮助用户快速实现录音文件的语音识别功能。该SDK支持多语言、多音频格式识别，适用于视频直播、电话语音、会议同传等多种场景。

二、前提条件

已开通Fun-ASR服务并获取API Key，需将API Key配置到环境变量（避免硬编码），防范安全风险。
若需临时访问权限或严格控制敏感操作，建议使用临时鉴权Token（有效期60秒，安全性更高），使用时替换API Key即可。
安装最新版DashScope SDK。

三、模型列表

（一）国际（新加坡）地域

模型名称	版本	支持语言	支持采样率	适用场景	支持音频格式	单价	免费额度
fun-asr（当前等同fun-asr-2025-11-07）	稳定版	中文（含多方言及多地区口音）、英文、日语	任意	视频直播、电话语音、会议同传等	aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv	$0.000035/秒	36,000秒（10小时），有效期90天
fun-asr-2025-11-07	快照版	同上	任意	同上	同上	同上	同上
fun-asr-2025-08-25	快照版	中文（普通话）、英文	任意	同上	同上	同上	同上
fun-asr-mtl（当前等同fun-asr-mtl-2025-08-25）	稳定版	中文（普通话、粤语）、英文、日语、韩语、越南语等30余种语言	任意	同上	同上	同上	同上
fun-asr-mtl-2025-08-25	快照版	同上	任意	同上	同上	同上	同上

（二）中国大陆（北京）地域

模型名称	版本	支持语言	支持采样率	适用场景	支持音频格式	单价
fun-asr（当前等同fun-asr-2025-11-07）	稳定版	中文（含多方言及多地区口音）、英文、日语	任意	视频直播、电话语音、会议同传等	aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv	$0.000032/秒
fun-asr-2025-11-07	快照版	同上	任意	同上	同上	同上
fun-asr-2025-08-25	快照版	中文（普通话）、英文	任意	同上	同上	同上
fun-asr-mtl（当前等同fun-asr-mtl-2025-08-25）	稳定版	中文（普通话、粤语）、英文、日语、韩语、越南语等30余种语言	任意	同上	同上	同上
fun-asr-mtl-2025-08-25	快照版	同上	任意	同上	同上	同上

四、核心约束

输入源要求：不支持本地音视频文件直传及base64格式音频，仅支持公网可访问的HTTP/HTTPS协议文件URL；SDK方式不支持阿里云OSS的oss://前缀临时URL，RESTful API支持但临时URL有效期仅48小时，不建议生产环境使用。
限流限制：文件上传凭证接口限流100 QPS，不支持扩容，禁止用于生产环境、高并发及压测场景。
文件限制：单次请求最多支持100个文件URL；单个音频文件不超过2GB，时长不超过12小时（超限制需预处理）。
格式兼容：支持多种音频格式，但因格式及变种众多，需提前测试验证识别效果。

五、快速开始

核心类Transcription提供异步提交任务、同步等待结果、异步查询结果三种接口，支持两种调用方式：

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

提交任务后阻塞线程，直至任务完成并返回结果：

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import os
import json

# 新加坡地域URL，北京地域替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 配置API Key（优先从环境变量获取，未配置则直接替换为sk-xxx）
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 提交识别任务
task_response = Transcription.async_call(
    model='fun-asr',
    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'
    ]
)

# 同步等待任务完成并获取结果
transcribe_response = 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!')

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

提交任务后，通过轮询查询结果：

from http import HTTPStatus
from dashscope.audio.asr import Transcription
import dashscope
import os
import json

# 新加坡地域URL，北京地域替换为：https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 配置API Key（优先从环境变量获取，未配置则直接替换为sk-xxx）
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 提交识别任务
transcribe_response = Transcription.async_call(
    model='fun-asr',
    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'
    ]
)

# 轮询查询任务状态，直至完成或失败
while True:
    if transcribe_response.output.task_status in ['SUCCEEDED', 'FAILED']:
        break
    transcribe_response = Transcription.fetch(task=transcribe_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!')

六、请求参数说明

通过Transcription.async_call方法设置请求参数，核心参数如下：

参数	类型	默认值	是否必须	说明
model	str	-	是	模型名称，参考模型列表
file_urls	list[str]	-	是	音频文件URL列表，支持HTTP/HTTPS，单次最多100个
vocabulary_id	str	-	否	热词ID，启用自定义热词时填写
channel_id	list[int]	[0]	否	需识别的音轨索引（多音轨独立计费）
special_word_filter	str	-	否	敏感词处理配置（JSON字符串），支持替换为*或直接过滤
diarization_enabled	bool	False	否	是否启用说话人分离（仅单声道支持）
speaker_count	int	-	否	说话人数量参考值（2-100，需启用分离功能）
language_hints	list[str]	["zh", "en"]	否	待识别语言代码，模型自动识别时可不设置

敏感词处理配置示例

{
  "filter_with_signed": {
    "word_list": ["测试"]  // 替换为等长*
  },
  "filter_with_empty": {
    "word_list": ["开始", "发生"]  // 直接过滤移除
  },
  "system_reserved_filter": true  // 启用系统内置敏感词过滤
}

七、响应结果说明

响应结果封装在TranscriptionResponse中，包含任务状态、子任务结果等信息，任务状态分为PENDING（排队中）、RUNNING（处理中）、SUCCEEDED（成功）、FAILED（失败）四种。

（一）成功响应示例（SUCCEEDED状态）

{
    "status_code":200,
    "request_id":"16668704-6702-9e03-8ab7-a32a5d7bb095",
    "output":{
        "task_id":"6351feef-9694-45d2-9d32-63454f2ffb8d",
        "task_status":"SUCCEEDED",
        "submit_time":"2025-02-13 17:31:20.681",
        "scheduled_time":"2025-02-13 17:31:20.703",
        "end_time":"2025-02-13 17:31:21.867",
        "results":[
            {
                "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/xxx.json",
                "subtask_status":"SUCCEEDED"
            },
            {
                "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/xxx.json",
                "subtask_status":"SUCCEEDED"
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":2,
            "FAILED":0
        }
    },
    "usage":{
        "duration":9
    }
}

（二）识别结果文件说明（transcription_url对应的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":", "
                        }
                    ]
                }
            ]
        }
    ]
}

八、关键接口说明

核心类Transcription通过from dashscope.audio.asr import Transcription引入，提供以下方法：

方法	签名	说明
async_call	`def async_call(cls, model: str, file_urls: List[str], **kwargs) -> TranscriptionResponse`	异步提交语音识别任务
wait	`def wait(cls, task: Union[str, TranscriptionResponse], **kwargs) -> TranscriptionResponse`	阻塞线程，等待任务完成并返回结果
fetch	`def fetch(cls, task: Union[str, TranscriptionResponse], **kwargs) -> TranscriptionResponse`	异步查询任务执行结果

九、常见问题

（一）功能特性类

是否支持Base64编码音频？
不支持，仅支持公网可访问的HTTP/HTTPS URL音频，不支持本地文件和二进制流。
如何生成公网可访问的音频URL？
推荐使用阿里云OSS：上传文件至OSS存储桶，设置“公共读”权限或生成临时访问链接；也可通过Web服务器、CDN托管生成URL，生成后需验证可用性（浏览器可播放或HTTP状态码200）。
多久能获取识别结果？
任务提交后进入排队状态，排队时间取决于队列长度和文件时长（通常数分钟），音频时长越长处理时间越久。

（二）故障排查类

一直轮询不到结果？
可能是限流导致，建议耐心等待，避免高并发提交任务。
无识别结果怎么办？
检查音频格式、采样率是否符合要求，可使用ffprobe工具验证音频信息：
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
子任务失败如何排查？
查看响应结果中output.results的code（错误码）和message（错误信息），根据提示定位问题（如文件下载失败、格式不支持等）。

Fun-ASR语音识别SDK文档.md 12 KB Pysyvä linkki Historia Raaka