录音文件识别接口说明 - 智能语音交互

录音文件识别通过异步任务将已录制的音频转换为文本。提交可通过 HTTP 或 HTTPS 下载的文件 URL 后，可轮询查询结果，也可通过回调接收结果；不支持直接提交本地文件。

计费与服务版本

录音文件识别提供试用版和商用版，计费规则请参见计费说明。

新接入时建议在任务参数中显式设置 version="4.0"，该版本的轮询和回调结果使用一致的驼峰命名字段。旧版回调格式请参见历史版本兼容。

使用限制

文件要求

支持 WAV、MP3、M4A、WMA、AAC、OGG、AMR、FLAC 录音文件，文件大小不超过 512 MB。WAV、MP3 文件支持单轨和双轨。

音频的语种、采样率需与项目中配置的识别模型匹配。模型选择方式和支持范围见语种和模型。

录音文件需存放在服务端可访问的文件服务器上。URL 的主机名需使用域名，不能使用 IP 地址；URL 不能包含空格，建议避免使用中文字符。

推荐将文件存放在阿里云 OSS。公共读文件可使用可访问的文件 URL；私有文件可使用预签名 URL 。生成方式请参见使用预签名 URL 下载或预览文件。

自行搭建的文件服务器需保证 HTTP 响应头 Content-Length 与响应体的实际长度一致。

可用URL	不可用URL
https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav	http://127.0.0.1/sample.wav D:\files\sample.wav

调用频率与任务时效

识别结果查询接口的用户级 QPS 限制为 100。

超过调用频率限制时会返回 Throttling.User。查询任务时需设置轮询间隔，控制请求频率。

免费用户每日可识别不超过 2 小时的录音文件。

提交任务后，免费用户的任务在 24 小时内完成，付费用户的任务在 6 小时内完成。识别结果在服务端保存 72 小时。

重要

上述处理时效不适用于一次性提交大规模数据的情况，例如半小时内提交超过 500 小时的录音。大规模识别需求请联系售前专家。

调用流程

根据音频的语种和采样率，在项目中配置对应的识别模型。
准备可下载的录音文件 URL。
使用 POST 请求调用 SubmitTask，在 Task 参数中传入任务配置。提交成功后，响应 JSON 的顶层 TaskId 字段返回任务 ID。
获取结果：轮询方式使用该 TaskId 调用 GetTaskResult；回调方式设置 enable_callback=true 和 callback_url，任务完成后，服务端将结果 POST 到回调地址。

交互流程

客户端与服务端的交互流程如下。任务 ID 位于响应 JSON 的 TaskId 字段。

录音文件识别的客户端与服务端交互流程

调用配置

接口采用 RPC 风格的 POP API，使用 AccessKey 签名鉴权。SubmitTask 使用 POST，GetTaskResult 使用 GET。SDK 中的产品名称为 nls-filetrans，地域、Endpoint 和 API 日期版本配置如下：

地域	regionId / endpointName	domain	API 日期版本（Version）
新加坡	ap-southeast-1	filetrans.ap-southeast-1.aliyuncs.com	2019-08-23

API 日期版本 Version 用于配置 POP 请求；任务参数中的小写 version 用于选择录音文件识别的服务版本。

请求说明

提交任务：SubmitTask

将以下 JSON 对象序列化为字符串，作为 Task 参数传入 POST 请求。示例中的 valid_times 仅识别指定时间段；需要识别整个文件时可省略该字段。

{
    "appkey": "your-appkey",
    "file_link": "https://gw.alipayobjects.com/os/bmw-prod/0574ee2e-f494-45a5-820f-63aee583045a.wav",
    "auto_split":false,
    "version": "4.0",
    "enable_words": false,
    "enable_sample_rate_adaptive": true,
    "valid_times": [
        {
            "begin_time": 200,
            "end_time":2000,
            "channel_id": 0
        }
    ]
}

Task 字段

参数	值类型	是否必选	说明
appkey	String	是	项目的 Appkey。项目中配置的识别模型需与音频的语种和采样率匹配。
file_link	String	是	录音文件的 HTTP 或 HTTPS 下载地址。服务端需能够通过该地址下载文件。
version	String	否	任务使用的服务版本。未设置时默认为 2.0；新接入时建议显式设置为 4.0。回调格式兼容说明请参见历史版本兼容。
enable_words	Boolean	否	是否返回词信息。默认值为 false。开启时需设置 version 为 4.0。
enable_sample_rate_adaptive	Boolean	否	是否将高于 16 kHz 的音频自动降采样至 16 kHz。默认值为 false。开启时需设置 version 为 4.0。
enable_callback	Boolean	否	是否启用回调。默认值为 false。
callback_url	String	否	回调服务地址。enable_callback 为 true 时必填。支持 HTTP 和 HTTPS，主机名需使用域名，不能使用 IP 地址。回调服务需能够接收 POST 请求。
auto_split	Boolean	否	是否启用智能分轨，通过句子结果中的 ChannelId 区分说话人。通常先发言的一方 ChannelId 为 0。支持 8 kHz 单通道音频。
enable_unify_post	Boolean	否	是否启用后处理。默认值为 false。auto_split 和 enable_unify_post 不能同时为 true。
enable_inverse_text_normalization	Boolean	否	是否启用逆文本规范化（ITN），将中文数字转换为阿拉伯数字。默认值为 false。开启时需设置 version 为 4.0、enable_unify_post 为 true。不会对词信息进行 ITN 转换。
enable_disfluency	Boolean	否	是否启用声音顺滑。默认值为 false。开启时需设置 version 为 4.0、enable_unify_post 为 true。
valid_times	List< ValidTime >	否	有效时间段列表，用于仅识别指定的音频片段。每个元素的字段见下方 ValidTime 字段说明。
max_end_silence	Integer	否	允许的最大结束静音，默认值为 450 ms。
max_single_segment_time	Integer	否	单句话的最大时长，最小值为 10000 ms，默认值为 20000 ms。
customization_id	String	否	通过 POP API 创建的定制语言模型 ID。默认不设置。
class_vocabulary_id	String	否	类热词表 ID。默认不设置。
vocabulary_id	String	否	泛热词表 ID。默认不设置。

ValidTime 字段

valid_times 的每个元素包含以下字段：

参数	值类型	是否必选	说明
begin_time	Int	是	有效时间段的起始点时间偏移，单位为毫秒。
end_time	Int	是	有效时间段的结束点时间偏移，单位为毫秒。
channel_id	Int	是	有效时间段的作用音轨序号（从0开始）。

查询结果：GetTaskResult

将提交响应中的任务 ID 作为 TaskId 参数传入 GET 请求，并按使用限制设置查询间隔。

属性	值类型	是否必选	说明
TaskId	String	是	识别任务ID。

返回说明

HTTP 状态表示 API 请求的处理结果，任务的识别状态由响应 JSON 中的 StatusCode 和 StatusText 表示。

提交响应

提交成功时返回以下 JSON：

{
        "TaskId": "4b56f0c4b7e611e88f34c33c2a60****",
        "RequestId": "E4B183CC-6CFE-411E-A547-D877F7BD****",
        "StatusText": "SUCCESS",
        "StatusCode": 21050000
}

属性	值类型	是否必选	说明
TaskId	String	是	识别任务ID。
RequestId	String	是	请求ID，仅用于联调。
StatusCode	Int	是	状态码。
StatusText	String	是	状态说明。

查询响应

识别成功

以下为单轨中文录音nls-sample-16k.wav的识别结果示例。

{
        "TaskId": "d429dd7dd75711e89305ab6170fe****",
        "RequestId": "9240D669-6485-4DCC-896A-F8B31F94****",
        "StatusText": "SUCCESS",
        "BizDuration": 2956,
        "SolveTime": 1540363288472,
        "StatusCode": 21050000,
        "Result": {
                "Sentences": [{
                        "EndTime": 2365,
                        "SilenceDuration": 0,
                        "BeginTime": 340,
                        "Text": "北京的天气。",
                        "ChannelId": 0,
                        "SpeechRate": 177,
                        "EmotionValue": 5.0
                }]
        }
}

排队中

任务尚未开始识别，等待后再次查询。

{
        "TaskId": "c7274235b7e611e88f34c33c2a60****",
        "RequestId": "981AD922-0655-46B0-8C6A-5C836822****",
        "StatusText": "QUEUEING",
        "StatusCode": 21050002
}

识别中

任务正在识别，等待后再次查询。

{
        "TaskId": "c7274235b7e611e88f34c33c2a60****",
        "RequestId": "8E908ED2-867F-457E-82BF-4756194A****",
        "StatusText": "RUNNING",
        "BizDuration": 0,
        "StatusCode": 21050001
}

识别失败

以下为文件下载失败的响应示例。根据 StatusCode 和 StatusText 处理错误。

{
        "TaskId": "4cf25b7eb7e711e88f34c33c2a60****",
        "RequestId": "098BF27C-4CBA-45FF-BD11-3F532F26****",
        "StatusText": "FILE_DOWNLOAD_FAILED",
        "BizDuration": 0,
        "SolveTime": 1536906469146,
        "StatusCode": 41050002
}

响应字段

Sentences 和 Words 位于 Result 对象中。

属性	值类型	是否必选	说明
TaskId	String	是	识别任务ID。
StatusCode	Int	是	状态码。
StatusText	String	是	状态说明。
RequestId	String	是	请求ID，用于调试。
Result	Object	否	任务成功时返回的识别结果对象。排队、运行中或失败响应不包含该对象。
Sentences	List< SentenceResult >	否	Result 中的句子结果列表，StatusText 为 SUCCESS 时返回。
Words	List< WordResult >	否	Result 中的词信息列表。需设置 enable_words 为 true，且 version 为 4.0。
BizDuration	Long	否	识别音频的时长，单位为毫秒。
SolveTime	Long	否	识别完成时间的 Unix 时间戳，单位为毫秒。任务尚未完成时不返回。

Sentences 字段

属性	值类型	是否必选	说明
ChannelId	Int	是	该句所属音轨ID。
BeginTime	Int	是	该句的起始时间偏移，单位为毫秒。
EndTime	Int	是	该句的结束时间偏移，单位为毫秒。
Text	String	是	该句的识别文本结果。
EmotionValue	Float	是	情绪能量值，取值为音量分贝值除以 10，范围为 1～10。
SilenceDuration	Int	是	本句与上一句之间的静音时长，单位为秒。
SpeechRate	Int	是	本句的平均语速。若识别语言为中文，则单位为：字数/分钟。若识别语言为英文，则单位为：单词数/分钟。

回调结果

设置 enable_callback=true、callback_url 和 version="4.0" 后，任务完成时服务端向回调地址发送 POST 请求。识别结果字段与轮询方式一致，示例如下：

{
        "Result": {
                "Sentences": [{
                        "EndTime": 2365,
                        "SilenceDuration": 0,
                        "BeginTime": 340,
                        "Text": "北京的天气。",
                        "ChannelId": 0,
                        "SpeechRate": 177,
                        "EmotionValue": 5.0
                }]
        },
        "TaskId": "36d01b244ad811e9952db7bb7ed2****",
        "StatusCode": 21050000,
        "StatusText": "SUCCESS",
        "RequestTime": 1553062810452,
        "SolveTime": 1553062810831,
        "BizDuration": 2956
}

RequestTime 为提交任务时的 Unix 时间戳，SolveTime 为识别完成时的 Unix 时间戳，单位均为毫秒。

词信息

设置 enable_words=true 且 version="4.0" 后，结果中包含 Words。轮询和回调返回的词信息一致。以下为中文录音的结果示例：

{
        "StatusCode": 21050000,
        "Result": {
                "Sentences": [{
                        "SilenceDuration": 0,
                        "EmotionValue": 5.0,
                        "ChannelId": 0,
                        "Text": "北京的天气。",
                        "BeginTime": 340,
                        "EndTime": 2365,
                        "SpeechRate": 177
                }],
                "Words": [{
                        "ChannelId": 0,
                        "Word": "北京",
                        "BeginTime": 640,
                        "EndTime": 940
                }, {
                        "ChannelId": 0,
                        "Word": "的",
                        "BeginTime": 940,
                        "EndTime": 1120
                }, {
                        "ChannelId": 0,
                        "Word": "天气",
                        "BeginTime": 1120,
                        "EndTime": 2020
                }]
        },
        "SolveTime": 1553236968873,
        "StatusText": "SUCCESS",
        "RequestId": "027B126B-4AC8-4C98-9FEC-A031158F****",
        "TaskId": "b505e78c4c6d11e9a213e11db149****",
        "BizDuration": 2956
}

Words 字段

属性	值类型	是否必选	说明
BeginTime	Int	是	词开始时间，单位为毫秒。
EndTime	Int	是	词结束时间，单位为毫秒。
ChannelId	Int	是	该词所属音轨ID。
Word	String	是	词信息。

状态与错误处理

StatusCode	StatusText	说明
21050000	SUCCESS	SubmitTask：任务提交成功。GetTaskResult：任务识别成功。
21050001	RUNNING	任务正在识别，等待后再次查询。
21050002	QUEUEING	任务正在排队，等待后再次查询。
21050003	SUCCESS_WITH_NO_VALID_FRAGMENT	任务完成，但未检测到有效语音片段。检查文件是否包含有效语音。

错误码

状态码	状态消息	原因及处理方法
41050001	USER_BIZDURATION_QUOTA_EXCEED	超出单日识别时长限制。如业务量较大，请联系商务洽谈，邮件地址：nls_support@service.aliyun.com。
41050002	FILE_DOWNLOAD_FAILED	文件下载失败。检查文件地址及服务端是否可以下载文件。
41050003	FILE_CHECK_FAILED	文件格式不符合要求。使用支持的录音文件格式。
41050004	FILE_TOO_LARGE	文件过大。检查录音文件大小是否超过 512 MB。
41050005	FILE_NORMALIZE_FAILED	文件归一化失败。检查文件是否损坏、是否可以正常播放。
41050006	FILE_PARSE_FAILED	文件解析失败。检查文件是否损坏、是否可以正常播放。
41050007	MKV_PARSE_FAILED	MKV 解析失败。检查文件是否损坏、是否可以正常播放。
41050008	UNSUPPORTED_SAMPLE_RATE	音频采样率与项目模型不匹配。检查音频采样率是否与 Appkey 所属项目配置的识别模型采样率一致。
41050009	UNSUPPORTED_ASR_GROUP	不支持的识别分组。检查 Appkey 是否正确，以及是否与签名使用的 AccessKey 属于同一账号。
41050010	FILE_TRANS_TASK_EXPIRED	TaskId 不存在或任务已过期。检查任务 ID 和结果保存时间。
41050011	REQUEST_INVALID_FILE_URL_VALUE	file_link 非法。检查文件 URL 的格式和可访问性。
41050012	REQUEST_INVALID_CALLBACK_VALUE	callback_url 非法。启用回调时需提供有效的回调 URL。
41050013	REQUEST_PARAMETER_INVALID	任务参数无效。Task 需为有效的 JSON 字符串。
41050014	REQUEST_EMPTY_APPKEY_VALUE	appkey 为空。填写项目的 Appkey。
41050015	REQUEST_APPKEY_UNREGISTERED	appkey 未注册或不匹配。检查 Appkey 是否正确，以及是否与签名使用的 AccessKey 属于同一账号。
41050021	RAM_CHECK_FAILED	RAM 权限检查失败。为 RAM 用户授予调用语音服务 API 的权限。
41050023	CONTENT_LENGTH_CHECK_FAILED	HTTP 响应的 Content-Length 与文件实际大小不一致，修正文件服务器的响应头。
41050024	FILE_404_NOT_FOUND	待下载的文件不存在。检查文件地址。
41050025	FILE_403_FORBIDDEN	无权限下载文件。检查是否有权限下载录音文件。
41050026	FILE_SERVER_ERROR	文件服务器不可用。检查文件服务器是否可用。
51050000	INTERNAL_ERROR	服务内部错误。偶发错误可忽略；重复出现时联系技术支持。
51050001	VAD_FAILED	语音活动检测失败。偶发错误可忽略；重复出现时联系技术支持。
51050002	RECOGNIZE_FAILED	识别失败。偶发错误可忽略；重复出现时联系技术支持。
51050003	RECOGNIZE_INTERRUPT	识别中断。偶发错误可忽略；重复出现时联系技术支持。
51050004	OFFER_INTERRUPT	写入队列中断。偶发错误可忽略；重复出现时联系技术支持。
51050005	FILE_TRANS_TIMEOUT	任务处理超时。偶发错误可忽略；重复出现时联系技术支持。
51050006	FRAGMENT_FAILED	音频分段失败。偶发错误可忽略；重复出现时联系技术支持。

语种和模型

语种和方言模型需在项目中配置，不能通过本接口的任务参数指定。支持语言模型定制和热词，详情请参见语言模型定制和热词。

在智能语音交互控制台的全部项目页面，选择目标项目，进入项目功能配置，在修改配置中按音频采样率选择模型。项目可选择 8 kHz 或 16 kHz 的识别模型，具体选项见项目配置。操作方法请参见管理项目。

历史版本兼容

任务参数 version="2.0" 的回调结果采用下划线命名字段，与 4.0 的驼峰命名字段不同。已按旧格式解析回调的应用，升级到 4.0 时需同步调整字段解析。旧版回调示例如下：

{
        "result": [{
                "begin_time": 340,
                "channel_id": 0,
                "emotion_value": 5.0,
                "end_time": 2365,
                "silence_duration": 0,
                "speech_rate": 177,
                "text": "北京的天气。"
        }],
        "task_id": "3f5d4c0c399511e98dc025f34473****",
        "status_code": 21050000,
        "status_text": "SUCCESS",
        "request_time": 1551164878830,
        "solve_time": 1551164879230,
        "biz_duration": 2956
}