本文介绍SenseVoice录音文件识别RESTful API的使用。
目前提供了提交任务接口和查询任务接口，通常情况下，您可以先调用提交任务接口开启任务，然后循环调用查询任务接口，直至任务完成。
前提条件
已开通服务并获取API Key。请配置API Key到环境变量，而非硬编码在代码中，防范因代码泄露导致的安全风险。
模型列表
模型名 | 模型简介 |
sensevoice-v1 | 语音识别大模型，支持50多种语言的识别，具备情感分析和音频事件检测功能，并默认提供标点符号预测及逆文本正则化（ITN）能力。 |
约束
服务不支持本地音/视频文件直传，输入源需为可通过公网访问的文件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；无时长限制。
如果希望处理的文件超过了上述限制，可尝试对文件进行预处理以降低文件尺寸。有关文件预处理的最佳实践可以查阅预处理视频文件以提高文件转写效率。
批处理音频数目
单次请求最多支持100个文件URL。
可识别语言
详情请参见语言列表。
重要SenseVoice每次只支持识别一种语言，请勿在
language_hints参数中指定多个语言代码。接口调用方式限制
不支持前端直接调用API，需通过后端中转。
提交任务接口
基本信息
接口描述 | 提交语音识别任务。 |
URL | |
请求方法 | POST |
请求头 | |
消息体 | 包含所有请求参数的消息体如下，对于可选字段，在实际业务中可根据需求省略： |
请求参数
参数 | 类型 | 默认值 | 是否必须 | 说明 |
model | string | - | 是 | 指定模型名。固定为 |
file_urls | array[string] | - | 是 | 待识别音/视频文件的URL列表，支持HTTP / HTTPS协议，单次请求最多支持100个URL。 |
channel_id | array[int] | [0] | 否 | 指定在多音轨文件中需要进行语音识别的音轨索引，以List的形式给出，例如 |
disfluency_removal_enabled | boolean | false | 否 | 过滤语气词，默认关闭。 |
language_hints | array[string] | ["auto"] | 否 | 指定识别语音中语言代码。SenseVoice只支持配置一个语种。默认使用“auto”自动检测语种。支持的语言代码请参见语言列表。 |
响应参数
参数 | 类型 | 说明 |
task_status | string | 任务状态。 |
task_id | string | 任务ID。 |
查询任务接口
基本信息
接口描述 | 查询语音识别任务执行情况和结果。 |
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_in_milliseconds | integer | 音轨中被判定为语音内容的时长（ms）。 重要 SenseVoice服务根据音频中AI识别出的有效语音时长计费，非语音段落（如静默、背景音）不计费。由于技术限制，系统判定的语音时段可能与实际存在细微差异，计费结果以服务端数据为准。 |
transcript | string | 段落级别的语音识别结果。 |
sentences | array | 句子级别的语音识别结果。 |
begin_time | integer | 开始时间戳（ms）。 |
end_time | integer | 结束时间戳（ms）。 |
text | string | 语音识别结果。 说明
|
完整示例
您可以使用编程语言自带的HTTP类库，来实现提交和查询任务的请求：先调用提交任务接口开启任务，然后循环调用查询任务接口，直至任务完成。
以Python为例，代码如下：
import requests
import json
import os
import time
# 若没有配置环境变量，请将下行替换为：api_key="your-api-key"。your-api-key为您实际的API Key
api_key = os.getenv("DASHSCOPE_API_KEY")
file_urls = [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav"
]
language_hints = ["en"]
# 提交语音识别任务，包含待识别文件url列表
def submit_task(api_key, file_urls) -> str:
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable",
}
data = {
"model": "sensevoice-v1",
"input": {"file_urls": file_urls},
"parameters": {
"channel_id": [0],
"language_hints": language_hints,
},
}
# 录音文件识别服务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(api_key=api_key, file_urls=file_urls)
print("task_id: ", task_id)
result = wait_for_complete(task_id)
print("transcription result: ", result)错误码
错误代码 Code | 错误信息Message（具体信息内容可能跟随场景有所变化） | 含义说明 |
InvalidFile.DecodeFailed | The audio file cannot be decoded. | 无法解码文件。请检查文件编码是否正确，并确认文件为正确的音频格式。 |
更多百炼平台相关错误码请参见错误信息。
更多示例
更多示例，请参见GitHub。
常见问题
请参见GitHub QA。
语言列表
Sensevoice支持如下50多种语言，其中top10为重点支持语言。可通过查询下表获取语言代码并配置language_hints参数以获得更佳的效果，默认支持中文和英文。
语言 | 语言代码 | |
重点语言 | 中文（Chinese） | zh |
英文（English） | en | |
粤语（Cantonese） | yue | |
日语（Japanese） | ja | |
韩语（Korean） | ko | |
俄语（Russian） | ru | |
法语（French） | fr | |
意大利语（Italian） | it | |
德语（German） | de | |
西班牙语（Spanish） | es | |
更多语言 | 加泰罗尼亚语（Catalan） | ca |
印度尼西亚语（Indonesian） | id | |
泰语（Thai） | th | |
荷兰语（Dutch） | nl | |
葡萄牙语（Portuguese） | pt | |
捷克语（Czech） | cs | |
波兰语（Polish） | pl | |
希腊语（Greek） | el | |
马来语（Malay） | ms | |
塔加洛语（Tagalog） | tl | |
保加利亚语（Bulgarian） | bg | |
克罗地亚语（Croatian） | hr | |
丹麦语（Danish） | da | |
土耳其语（Turkish） | tr | |
越南语（Vietnamese） | vi | |
希伯来语（Hebrew ） | he | |
匈牙利语（Hungarian） | hu | |
乌克兰语（Ukrainian） | uk | |
爪哇语（Javanese） | jw | |
乌兹别克语（Uzbek） | uz | |
挪威（Norwegian） | no | |
罗马尼亚（Romanian） | ro | |
瑞典语（Swedish） | sv | |
波斯语（Persian） | fa | |
泰米尔语（Tamil） | ta | |
阿塞拜疆语（Azerbaijani） | az | |
孟加拉语（Bengali） | bn | |
缅甸语（Myanmar） | my | |
高棉语（Khmer ） | km | |
印地语（Hindi） | hi | |
卡纳达语（Kannada ） | kn | |
老挝语（Lao） | lo | |
马拉雅拉姆语（Malayalam） | ml | |
马拉地语（Marathi） | mr | |
蒙古语（Mongolian） | mn | |
尼泊尔语（Nepali） | ne | |
旁遮普语（Punjabi ） | pa | |
僧伽罗语（Sinhala） | si | |
斯瓦希里语（Swahili） | sw | |
泰卢固语（Telugu） | te | |
乌尔都语（Urdu） | ur | |
豪萨语（Hausa） | ha | |