本文介绍Qwen-Audio-3.x-ASR-Flash-Filetrans/Fun-ASR非实时语音识别Python SDK的参数和接口细节。
用户指南:非实时语音识别。关于支持的音频格式、文件大小限制、时长限制等输入要求,请参见音频规格。
核心类(Transcription)提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行非实时语音识别:
请求参数通过核心类(Transcription)的
示例 1(说明):
需要关注的参数:
需要关注的参数:
识别结果保存为JSON文件。
需要关注的参数如下:
示例 1(方法签名):
示例 2(方法签名):
示例 3(方法签名):
详情请参见管理异步任务:支持批量查询24小时内提交的非实时语音识别任务,同时支持取消
如遇报错问题,请参见错误码进行排查。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
使用SDK时,若录音文件存储在阿里云OSS,不支持使用以
任务提交后将进入排队(PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内,请耐心等待。并且音频时长越长,所需时间越久。
如遇代码报错问题,请根据错误码中的信息进行排查。
可能是限流原因,请耐心等待。
请检查音频格式和采样率是否正确且符合参数约束。
可以使用ffprobe工具获取音频的容器、编码、采样率、声道等信息:
前提条件
-
已开通服务并获取与配置 API Key。请配置API Key到环境变量,而非硬编码在代码中,防范因代码泄露导致的安全风险。
当您需要为第三方应用或用户提供临时访问权限,或者希望严格控制敏感数据访问、删除等高风险操作时,建议使用临时鉴权Token。与长期有效的 API Key 相比,临时鉴权 Token 具备时效性短(60秒)、安全性高的特点,适用于临时调用场景,能有效降低API Key泄露的风险。使用方式:在代码中,将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。
- 安装最新版DashScope SDK。
快速开始
核心类(Transcription)提供了异步提交任务、同步等待任务结束和异步查询任务执行结果的接口。可通过如下两种调用方式进行非实时语音识别:
- 异步提交任务+同步等待任务结束:提交任务后,阻塞当前线程直到任务结束并获取识别结果。
- 异步提交任务+异步查询任务执行结果:提交任务后,在需要的时候通过调用查询任务接口获取任务的执行结果。
异步提交任务+同步等待任务结束
-
调用核心类(Transcription)的
async_call方法并设置请求参数。- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 - 每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
-
调用核心类(Transcription)的
wait方法同步等待任务结束。 任务的状态包括PENDING、RUNNING、SUCCEEDED和FAILED。当任务处于PENDING或RUNNING状态时,wait接口将被阻塞。当任务处于SUCCEEDED或FAILED状态时,wait接口不再阻塞并返回任务的执行结果。wait返回TranscriptionResponse。
点击查看完整示例
点击查看完整示例
异步提交任务+异步查询任务执行结果
-
调用核心类(Transcription)的
async_call方法并设置请求参数。- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
PENDING)状态,排队时间取决于队列长度和文件时长,无法明确给出,通常在数分钟内。任务开始处理后,语音识别将以数百倍加速完成。 - 每一个任务完成后,识别结果和URL下载链接有效期为24小时,超时后无法查询任务或通过先前查询结果中的URL下载结果。
- 文件转写服务对通过API提交的任务采取尽力服务原则进行处理。任务提交后将进入排队(
-
循环调用核心类(Transcription)的
fetch方法直到获取最终的任务结果。 当任务状态为SUCCEEDED或FAILED时,停止轮询并处理结果。fetch返回TranscriptionResponse。
点击查看完整示例
点击查看完整示例
接口地址
https://maas.qianwenaiapi.com/api/v1
请求参数
请求参数通过核心类(Transcription)的async_call方法进行设置。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| model | str | 是 | 指定模型名。支持Qwen-Audio-3.x-ASR-Flash-Filetrans和Fun-ASR系列模型,详情请参见支持的模型与地域。 |
| file_urls | list[str] | 是 | 音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求仅支持1个URL。关于支持的音频格式、文件大小限制、时长限制等输入要求,请参见音频规格。 若录音文件存储在阿里云OSS,使用RESTful API方式支持使用以oss://为前缀的临时 URL,使用SDK方式不支持使用以 oss://为前缀的临时 URL。 提示: - 临时 URL 有效期48小时,过期后无法使用,请勿用于生产环境。
|
| keep_dialect | bool | 否 | 仅 qwen-audio-3.1-asr-flash-filetrans 支持。默认 false,将方言转写为普通话;设为 true 时保留方言表达。作为同名关键字参数传入。完整参数说明请参见API 参考。 |
| vocabulary_id | str | 否 | 预编译热词列表 ID。 需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。 适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。 使用方法请参见预编译热词。 |
| vocabulary | dict | 否 | 即时热词。 以键值对形式传入,键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。权重取值范围为 [1, 5] 或 50:取 [1, 5] 时值越大模型越倾向输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词数量最多不超过 50 个。 适用于临时性、会话级别的热词优化。 与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。 提示: 仅qwen-audio-3.1-asr-flash-filetrans、qwen-audio-3.0-asr-flash-filetrans支持即时热词。 示例: 示例 1 请参见表格下方 |
| channel_id | list[int] | 否 | 指定在多音轨音频文件中需要识别的音轨索引,索引从 0 开始。例如,[0] 表示识别第一个音轨,[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数,则默认处理第一个音轨。 提示: 指定的每一个音轨都将独立计费。例如,为单个文件请求 [0, 1] 会产生两笔独立的费用。 默认值:[0]。 |
| special_word_filter | str | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。 |
| diarization_enabled | bool | 否 | 是否启用说话人分离,默认关闭。 仅适用于单声道音频,多声道音频不支持说话人分离。 启用该功能后,识别结果中将显示speaker_id字段,用于区分不同说话人。 说明: 如果启用说话人分离功能,建议音频时长不超过2小时,否则可能导致识别失败或超时。 默认值:False。 有关speaker_id的示例,请参见识别结果说明。 |
| speaker_count | int | 否 | 提示: 仅在开启说话人分离功能(diarization_enabled设置为True)时生效。 说话人数量参考值。取值范围为2至100的整数(包含2和100)。 默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。 无默认值。 |
| language_hints | list[str] | 否 | 设置待识别语言代码。如果无法提前确定语种,可不设置,模型会自动识别语种。 对于 Qwen-Audio-3.x-ASR-Flash-Filetrans 系列模型,最多支持设置 4 个值,即便设置超出 4 个,也仅前 4 个生效;对于 Fun-ASR 系列模型,仅支持设置 1 个值,即便设置多个,也仅第一个生效。
|
响应结果
TranscriptionResponse
TranscriptionResponse封装了任务的基本信息(task_id和task_status)和执行结果(output属性对应的内容,参见TranscriptionOutput)。
点击查看 TranscriptionResponse 结构示例
点击查看 TranscriptionResponse 结构示例
| 参数 | 说明 |
|---|---|
| status_code | HTTP请求状态码。 |
| code |
|
| message |
|
| task_id | 任务ID。 |
| task_status | 任务状态。 有 PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 SUCCEEDED,需通过subtask_status字段判断具体子任务结果。 |
| results | 子任务识别结果。 |
| subtask_status | 子任务状态。 有 PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。 |
| file_url | 被识别音频的URL。 |
| transcription_url | 音频识别结果对应的URL。 识别结果保存为JSON文件,您可以通过 transcription_url对应的链接下载文件或直接通过HTTP请求读取该文件中的内容。JSON文件的内容请参见识别结果说明。 |
TranscriptionOutput
TranscriptionOutput对应TranscriptionResponse的output属性,代表当前任务执行结果。
点击查看 TranscriptionOutput 结构示例
点击查看 TranscriptionOutput 结构示例
- PENDING状态
- RUNNING状态
- SUCCEEDED 状态
- FAILED 状态
| 参数 | 说明 |
|---|---|
| code | 代表错误码。可以结合message字段,对照错误码排查问题。 |
| message | 代表错误信息。可以结合code字段,对照错误码排查问题。 |
| task_id | 任务ID。 |
| task_status | 任务状态。 有 PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为 SUCCEEDED,需通过subtask_status字段判断具体子任务结果。 |
| results | 子任务识别结果。 |
| subtask_status | 子任务状态。 有 PENDING、RUNNING、SUCCEEDED和FAILED这四种状态。 |
| file_url | 被识别音频的URL。 |
| transcription_url | 音频识别结果对应的URL。 识别结果以JSON格式保存在一个JSON文件中,您可以通过 transcription_url对应的链接下载文件或直接通过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 | 预测出的词之后的标点符号(如有)。 |
关键接口
核心类(Transcription)
Transcription可以通过“from dashscope.audio.asr import Transcription”方式引入。
| 成员方法 | 方法签名 | 说明 |
|---|---|---|
| async_call | 示例 1 请参见表格下方 | 异步提交语音识别任务。 |
| wait | 示例 2 请参见表格下方 | 阻塞当前线程直到异步任务结束(任务状态为SUCCEEDED或FAILED)。 该方法返回TranscriptionResponse。 |
| fetch | 示例 3 请参见表格下方 | 异步查询当前任务执行结果。 该方法返回TranscriptionResponse。 |
其他接口:批量查询任务状态/取消任务
详情请参见管理异步任务:支持批量查询24小时内提交的非实时语音识别任务,同时支持取消PENDING(排队)状态的任务。
错误码
如遇报错问题,请参见错误码进行排查。
当任务包含多个子任务时,只要存在任一子任务成功,整个任务状态将标记为SUCCEEDED,需通过subtask_status字段判断具体子任务结果。
错误返回示例:
常见问题
功能特性
Q:是否支持Base64编码方式的音频?
不支持Base64编码方式的音频。仅支持可通过公网访问的 URL 所指向的音频的识别,不支持识别二进制流,也不支持直接识别本地文件。
Q:如何将音频文件以公网可访问的URL形式提供?
通常遵循以下几个步骤(这里为您提供一种思路,具体情况因不同存储产品而异,推荐将音频上传至阿里云OSS):
1、选择存储和托管方式
1、选择存储和托管方式
如以下这几种:
-
对象存储服务(推荐):
- 使用云服务商的对象存储服务(如阿里云OSS),将音频文件上传到存储桶中,并设置为公开访问。
- 优点:高可用性、支持 CDN 加速、易于管理。
-
Web 服务器:
- 将音频文件放置在支持 HTTP/HTTPS 访问的 Web 服务器上(如 Nginx、Apache)。
- 优点:适合小型项目或本地测试。
-
内容分发网络(CDN):
- 将音频文件托管在 CDN 上,通过 CDN 提供的 URL 访问。
- 优点:加速文件传输,适合高并发场景。
2、上传音频文件
2、上传音频文件
根据选择的存储/托管方式,将音频上传,如:
-
对象存储服务:
- 登录云服务商的控制台,创建存储桶。
- 上传音频文件,并设置文件权限为“公共读”或生成临时访问链接。
-
Web 服务器:
- 将音频文件放置在服务器指定目录下(如
/var/www/html/audio/)。 - 确保文件可以通过 HTTP/HTTPS 访问。
- 将音频文件放置在服务器指定目录下(如
3、生成公网可访问的URL
3、生成公网可访问的URL
例如:
-
对象存储服务:
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
https://<bucket-name>.<region>.aliyuncs.com/<file-name>)。 - 如果需要更友好的域名,可以绑定自定义域名并开启 HTTPS。
- 文件上传后,系统会自动生成一个公网访问 URL(通常格式为
-
Web 服务器:
- 文件的访问 URL 通常是服务器地址加上文件路径(如
https://your-domain.com/audio/file.mp3)。
- 文件的访问 URL 通常是服务器地址加上文件路径(如
-
CDN:
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
https://cdn.your-domain.com/audio/file.mp3)。
- 配置 CDN 加速后,使用 CDN 提供的 URL(如
4、验证URL的可用性
4、验证URL的可用性
公网环境下,确保生成的 URL 可以正常访问,例如:
- 在浏览器中打开 URL,检查是否能播放音频文件。
- 使用工具(如
curl或 Postman)验证 URL 是否返回正确的 HTTP 响应(状态码 200)。
oss://为前缀的临时 URL。
使用RESTful API时,若录音文件存储在阿里云OSS,支持使用以 oss://为前缀的临时 URL:
- 临时 URL 有效期48小时,过期后无法使用,请勿用于生产环境。
- 文件上传凭证接口限流为 100 QPS 且不支持扩容,请勿用于生产环境、高并发及压测场景。
- 生产环境建议使用阿里云OSS 等稳定存储,确保文件长期可用并规避限流问题。