接口说明
对一分钟内的短语音进行识别,适用于对话聊天、控制口令、语音输入法、语音搜索等较短的语音识别场景。
功能简介
NUI SDK提供更小的工具包和更完善的状态管理。为满足不同用户需求,NUI SDK既能提供全链路的语音能力,同时可做原子能力SDK进行使用,并保持接口的统一。
使用须知
输入格式:PCM编码、16bit采样位数、单声道(mono)。
音频采样率:8000Hz/16000Hz。
时长限制:语音数据时长不能超过60s。
设置返回结果:是否返回中间识别结果、在后处理中添加标点、将中文数字转为阿拉伯数字输出。
设置多语言识别:在控制台编辑项目中进行模型选择,详情请参见模型选择。
服务地址
访问类型 | 说明 | URL |
---|---|---|
外网访问 | 所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL)。 | wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1 |
上海ECS内网访问 | 使用阿里云上海ECS(即ECS地域为华东2(上海)),可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。 说明 使用内网访问方式,将不产生ECS实例的公网流量费用。-关于ECS的网络类型请参见网络类型。 | ws://nls-gateway.cn-shanghai-internal.aliyuncs.com:80/ws/v1 |
交互流程
下图展示iOS SDK、Android SDK的交互流程。

所有服务端的响应都会在返回信息的header包含表示本次识别任务的task_id参数,请记录该值,如果出现错误,请将task_id和错误信息提交到工单。
1. 鉴权和初始化
客户端在与服务端建立WebSocket连接的时候,使用Token进行鉴权。关于Token获取请参见获取Token。
初始化参数如下。
参数 | 类型 | 是否必选 | 说明 |
---|---|---|---|
workspace | String | 是 | 工作目录路径,SDK从该路径读取配置文件。 |
app_key | String | 是 | 管控台创建项目的appkey。 |
token | String | 是 | 请确保该token可以使用并在有效期内。 说明 token可以在初始化时设置,也可通过参数设置进行更新。 |
device_id | String | 是 | 设备标识,唯一表示一台设备(如Mac地址/SN/UniquePsuedoID)。 |
debug_path | String | 否 | debug目录,当初始化SDK时的 |
save_wav | String | 否 | 当初始化SDK时的 |
2. 开始识别
客户端发起一句话识别请求前需要进行参数设置,各参数由SDK中setParams接口以JSON格式设置,该参数只需设置一次。各参数含义如下。
参数 | 类型 | 是否必选 | 说明 |
---|---|---|---|
appkey | String | 否 | 管控台创建的项目appkey,一般在初始化时设置。 |
token | String | 否 | 如果需要更新,则进行设置。 |
service_type | Int | 是 | 需要请求的语音服务类型,一句话识别为“0”。 |
direct_ip | String | 否 | 支持客户端自行DNS解析后传入IP进行访问。 |
nls_config | JsonObject | 否 | 访问语音服务相关的参数配置,详情请参见下表。 |
参数nls_config配置如下。
参数 | 类型 | 是否必选 | 说明 |
---|---|---|---|
sr_format | String | 否 | 音频编码格式,支持OPUS编码和PCM原始音频。默认值:OPUS。 说明 如果使用8000Hz采样率,则只支持PCM格式。 |
sample_rate | Integer | 否 | 音频采样率,默认值:16000Hz。根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。 |
enable_intermediate_result | Boolean | 否 | 是否返回中间识别结果,默认值:False。 |
enable_punctuation_prediction | Boolean | 否 | 是否在后处理中添加标点,默认值:False。 |
enable_inverse_text_normalization | Boolean | 否 | 是否在后处理中执行ITN。设置为true时,中文数字将转为阿拉伯数字输出,默认值:False。 说明 不会对词信息进行ITN转换。 |
customization_id | String | 否 | 自学习模型ID。 |
vocabulary_id | String | 否 | 定制泛热词ID。 |
enable_voice_detection | Boolean | 否 | 是否启动语音检测。默认值:False。 |
max_start_silence | Integer | 否 | 当 |
max_end_silence | Integer | 否 | 当 |
3. 发送数据
客户端循环发送语音数据,持续接收识别结果。
若enable_intermediate_result设置为true,SDK会持续多次通过onNuiEventCallback回调上报EVENT_ASR_PARTIAL_RESULT事件,即中间识别结果:
{ "header": { "namespace": "SpeechRecognizer", "name": "RecognitionResultChanged", "status": 20000000, "message_id": "e06d2b5d50ca40d5a50d4215c7c8****", "task_id": "4c3502c7a5ce4ac3bdc488749ce4****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "result": "北京的天气" } }
header对象参数说明:
参数
类型
说明
namespace
String
消息所属的命名空间。
name
String
消息名称。RecognitionResultChanged表示获取到中间识别结果。
status
Integer
状态码。表示请求是否成功,见服务状态码。
message_id
String
本次消息的ID,由SDK自动生成。
task_id
String
任务全局唯一ID,请记录该值,便于排查问题。
status_text
String
状态消息。
payload对象参数说明:
参数
类型
说明
result
String
中间识别结果。
说明最后一次获取的中间识别结果与最终的识别的结果不一定相同,请以EVENT_ASR_RESULT事件的结果为最终识别结果。
若enable_intermediate_result设置为false,此步服务端不返回任何消息。
4. 结束识别
客户端发送停止一句话识别请求,通知服务端语音数据发送结束,停止语音识别,服务端返回最终识别结果:
{
"header": {
"namespace": "SpeechRecognizer",
"name": "RecognitionCompleted",
"status": 20000000,
"message_id": "10490c992aef44eaa4246614838f****",
"task_id": "4c3502c7a5ce4ac3bdc488749ce4****",
"status_text": "Gateway:SUCCESS:Success."
},
"payload": {
"result": "北京的天气。"
}
}
header对象参数说明:
参数 | 类型 | 说明 |
---|---|---|
namespace | String | 消息所属的命名空间。 |
name | String | 消息名称。RecognitionCompleted表示识别完成。 |
status | Integer | 状态码。表示请求是否成功,见服务状态码。 |
message_id | String | 本次消息的ID,由SDK自动生成。 |
task_id | String | 任务全局唯一ID,请记录该值,便于排查问题。 |
status_text | String | 状态消息。 |
payload对象参数说明:
参数 | 类型 | 说明 |
---|---|---|
result | String | 一句话识别最终结果。 |
错误码
识别成功
错误码 | 错误信息 | 描述 |
---|---|---|
0 | SUCCESS | 成功 |
配置或参数错误
错误码 | 错误消息 | 描述 | 解决方案 |
---|---|---|---|
240999 | DEFAULT_ERROR | 内部默认错误。 | 内部未明确错误,可提工单通过日志文件寻求支持。 |
240001 | NUI_CONFIG_INVALID | 配置文件错误。 | 配置文件错误,请确认传入的资源路径内是否有资源文件。如果是Android平台,请参考代码样例主动使用copyAssets接口。 |
240002 | ILLEGAL_PARAM | 非法参数。 | 请确认传入的格式是否正确,包括字段类型,值范围限制。 |
240003 | ILLEGAL_INIT_PARAM | 初始化参数非法。 | 请确认初始化参数格式错误或缺少必须字段。 |
240004 | NECESSARY_PARAM_LACK | 缺少必须参数。 | 请确认接口调用时的必须参数。 |
240005 | NULL_PARAM_ERROR | 参数为空。 | 确认参数是否为空。 |
240006 | NULL_LISTENER_ERROR | 未定义事件回调。 | 确认回调事件是否正确赋值。 |
240007 | NULL_DIALOG_ERROR | 无有效对话实例,一般在内部状态错误时发生。 | 请确认接口调用前是否为正确状态,可使用cancel接口恢复idle状态。仍不能解决可提工单获得支持。 |
240008 | NULL_ENGINE_ERROR | 无有效引擎实例,请检查是否初始化成功。 | 请确认是否初始化成功。 |
240009 | ILLEGAL_DATA | 传入音频数据地址或长度非法。 | 请确认传入的数据长度值。 |
SDK状态错误
错误码 | 错误消息 | 描述 | 解决方案 |
---|---|---|---|
240010 | ILLEGAL_REENTRANT | 退出后调用SDK接口。 | 不影响功能时可忽略。 |
240011 | SDK_NOT_INIT | SDK未正确初始化。 | 确认初始化返回值正确再进行其他接口使用。 |
240012 | SDK_ALREADY_INIT | 重复调用SDK初始化接口。 | 确认初始化调用逻辑。 |
240013 | DIALOG_INVALID_STATE | 内部对话状态错误。 | 请阅读SDK流程图,确认是否在错误状态下调用接口。 |
240014 | STATE_INVALID | SDK内部状态错误。 | 同DIALOG_INVALID_STATE。 |
240015 | ILLEGAL_FUNC_CALL | 该模式无法调用接口。 | 请确认接口调用是否合理。 |
系统调用错误
错误码 | 错误信息 | 描述 | 解决方法 |
---|---|---|---|
240020 | MEM_ALLOC_ERROR | 内存分配错误。 | 检查内存是否不足。 |
240021 | FILE_ACCESS_FAIL | 文件访问错误。 | 检查文件读写权限是否提供。 |
240022 | CREATE_DIR_ERROR | 创建目录错误。 | 检查是否有写权限。 |
SDK内部调用错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240030 | CREATE_NUI_ERROR | 引擎创建失败。 | 创建实例失败,一般为系统资源不足。 |
240031 | TEXT_DIALOG_START_FAIL | 发起文本理解失败。 | 文本转语义理解失败,检查网络连接或url以及token等信息是否有效。 |
240032 | TEXT_CANCEL_START_FAIL | 取消文本理解失败。 | 可忽略。 |
240033 | WUW_DUPLICATE | 动态唤醒词重复。 | 可忽略。 |
本地引擎调用错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240040 | CEI_INIT_FAIL | 本地引擎初始化失败。 | 请确认本地引擎的模型是否有效,目录是否可读写。可提交工单跟进。 |
240041 | CEI_SET_PARAM_FAIL | 引擎参数设置失败。 | 请提工单。 |
240042 | CEI_COMPILE_GRAMMER_FAIL | 语法编译失败。 | 可忽略。 |
240043 | CEI_STOP_FAIL | 停止识别失败。 | 请提工单。 |
240044 | CEI_CANCEL_FAIL | 取消识别失败。 | 请提工单。 |
240045 | CEI_UNLOAD_KWS_FAIL | 取消唤醒词失败。 | 请提工单。 |
240046 | GET_WUW_ERROR | 获取唤醒词失败。 | 请提工单。 |
音频错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240050 | SELECT_RECORDER_ERROR | 选择音频设备错误。 | 内部错误,请提工单。 |
240051 | UPDATE_AUDIO_ERROR | 推送音频错误,一般为输入音频长度大于所需音频。 | 确认推送的音频长度是否非法。 |
240052 | MIC_ERROR | 连续2s未获取到音频。 | 请确认在音频数据回调中是否正确提供所需长度的音频。 |
调用超时错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240080 | ENGINE_INIT_TIMEOUT | 初始化引擎超时。 | 如果偶现可忽略,否则请提工单。 |
240081 | SET_PARAM_TIMEOUT | 设置参数超时。 | 如果偶现可忽略,否则请提工单。 |
240082 | SET_WUW_TIMEOUT | 设置唤醒词超时。 | 如果偶现可忽略,否则请提工单。 |
240083 | SELECT_RECORDER_TIMEOUT | 选择录音设备超时。 | 如果偶现可忽略,否则请提工单。 |
240084 | STOP_TIMEOUT | 结束对话超时。 | 如果偶现可忽略,否则请提工单。 |
240085 | ASR_ENGINE_STOP_TIMEOUT | 结束引擎超时。 | 如果偶现可忽略,否则请提工单。 |
240086 | UNLOAD_DYNAMIC_WUW_TIMEOUT | 取消动态唤醒词超时。 | 如果偶现可忽略,否则请提工单。 |
240087 | ADD_DYNAMIC_WUW_TIMEOUT | 增加动态唤醒词超时。 | 如果偶现可忽略,否则请提工单。 |
240100 | WAIT_TIMEOUT | 引擎接口调用超时。 | 如果偶现可忽略,否则请提工单。 |
240101 | HANDLE_API_TIMEOUT | API层接口调用超时。 | 如果偶现可忽略,否则请提工单。 |
网络错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240060 | CREATE_DA_REQUEST_ERROR | 创建对话助手实例失败。 | 可忽略。 |
240061 | START_DA_REQUEST_ERROR | 发起对话助手请求失败。 | 可忽略。 |
240062 | DEFAULT_NLS_ERROR | 服务端发生错误。说明该错误同时包含服务端返回错误内容,具体请参见服务端错误码。 | 请参考服务端返回码进一步定位。 |
240063 | SSL_ERROR | 创建ssl实例错误。 | 偶现请忽略,否则请提交工单。 |
240064 | SSL_CONNECT_FAILED | ssl连接失败。 | 连接异常,请检查服务url或者本地网络连接是否正常。 |
240065 | HTTP_CONNECT_FAILED | HTTP连接失败。 | 服务连接错误,可通过日志文件查看HTTP返回值确认原因,或提工单跟进。 |
240066 | DNS_FAILED | DNS解析失败。 | 请检查本地网络是否正常,DNS服务是否正常。 |
240067 | CONNECT_FAILED | socket连接失败。 | 检查网络连接。 |
240068 | SERVER_NOT_ACCESS | 服务端无法访问。 | 请检查token是否过期或者url是否正确,仍无法定位请提工单。 |
240069 | SOCKET_CLOSED | socket已关闭。 | 偶现可忽略,否则提交工单跟进。 |
240070 | AUTH_FAILED | 鉴权失败。 | 请检查是否提供正确的ak_serect,ak_id,app_key,sdk_code,device_id等信息,以及确认是否开通足够配额。 |
240071 | HTTPDNS_FAILED | 使用客户端传入的IP连接失败。 | 如果使用直接传入IP进行访问,请确认IP是否可访问。 |
240072 | HTTP_SEND_FAILED | 文件转写HTTP发送失败。 | 确认网络连接是否正常。 |
240073 | HTTP_RECEIVE_FAILED | 文件转写HTTP接收失败。 | 确认网络连接是否正常。 |
240074 | HTTP_RESPONSE_ERROR | 文件转写接收内容解析失败。 | 服务端返回内容错误,请提工单跟进。 |
240075 | HTTP_SERVER_ERROR | 文件转写服务错误,详细错误请参考服务错误码。 | 请参考服务端错误码进一步确认原因。 |
网络超时错误
错误码 | 错误消息 | 描述 | 解决方法 |
---|---|---|---|
240090 | UPDATE_CONTEXT_TIMEOUT | 更新客户端信息超时 | 偶现请忽略,否则提交工单。 |
240091 | CONNECTION_TIMEOUT | 网络连接超时 | 偶现请忽略,否则提交工单。 |
240092 | PARTIAL_ASR_TIMEOUT | 获取中间识别结果超时 | 偶现请忽略,否则提交工单。 |
240093 | ASR_TIMEOUT | 获取最终识别结果超时 | 偶现请忽略,否则提交工单。 |
240094 | DIALOG_TIMEOUT | 获取对话理解结果超时 | 偶现请忽略,否则提交工单。 |
240095 | WWV_TIMEOUT | 获取云端唤醒确认结果超时 | 偶现请忽略,否则提交工单。 |
服务端错误码
当收到EVENT_ASR_ERROR事件,并且错误码为DEFAULT_NLS_ERROR(240062)或HTTP_SERVER_ERROR(240075)时,可以通过错误事件header中status字段获取服务端错误码进行进一步问题定位。
错误码 | 原因 | 解决方法 |
---|---|---|
40000001 | 身份认证失败。 | 检查使用的令牌是否正确、是否过期。 |
40000002 | 无效的消息。 | 检查发送的消息是否符合要求。 |
403 | 令牌过期或无效的参数 |
|
40000004 | 空闲超时。 | 确认是否长时间(10秒)未发送数据到服务端。 |
40000005 | 请求数量过多。 | 检查是否超过了并发连接数或者每秒钟请求数。如果超过并发数,建议从免费版升级到商用版,或者商用版扩容并发资源。 |
40000000 | 默认的客户端错误码。 | 查看错误消息或提交工单。 |
41010120 | 客户端超时错误。 | 客户端连续10秒及以上没有发送数据,导致客户端超时错误。 |
50000000 | 默认的服务端错误。 | 如果偶现可以忽略,重复出现请提交工单。 |
50000001 | 内部调用错误。 | 如果偶现可以忽略,重复出现请提交工单。 |
52010001 | 内部调用错误。 | 如果偶现可以忽略,重复出现请提交工单。 |
40010001 | 不支持的接口。 | 使用了不支持的接口,如果使用SDK请提交工单。 |
40010002 | 不支持的指令。 | 使用了不支持的指令,如果使用SDK请提交工单。 |
40010003 | 无效的指令。 | 指令格式错误,如果使用SDK请提交工单。 |
40010004 | 客户端提前断开连接。 | 检查是否在请求正常完成之前关闭了连接。 |
40010005 | 任务状态错误。 | 发送了当前任务状态不能处理的指令。 |
40020105 | 应用不存在。 | 解析路由时找不到应用。 |
40020106 | appkey和token不匹配。 | 检查应用appkey是否正确,是否与令牌归属同一个账号。 |
40020503 | 子账户鉴权失败。 | 使用父账户对调用的子账户授权POP API的访问权限。 |
41040201 | 客户端10s内停止发送数据。 | 检查网络问题,或者检查业务中是否存在不发数据的情况。 |
41040202 | 客户端发送数据过快,服务器资源已经耗尽。 | 检测客户端发包是否过快,是否按照1:1的实时率发包。 |
41040203 | 客户端发送音频格式不正确。 | 请将音频数据的格式转换为SDK目前支持的音频格式。 |
41040204 | 客户端调用方法异常。 | 客户端应该先调用发送请求接口,发送请求完毕后再调用其他接口。 |
41040205 | 客户端设置MAXSILENCE_PARAM方法异常。 | 参数MAXSILENCE_PARAM的范围为200~2000。 |
41050008 | 采样率不匹配。 | 检查调用时设置的采样率和管控台上appkey绑定的ASR模型采样率是否一致。 |
51040101 | 服务端内部错误。 | 未知错误。 |
51040103 | 实时语音识别服务不可用 | 检查实时语音识别服务是否有任务堆积等导致任务提交失败 |
51040104 | 请求实时语音识别服务超时。 | 排查实时语音识别日志。 |
51040105 | 调用实时语音识别服务失败。 | 检查实时语音识别服务是否启动,端口是否正常开启。 |
51040106 | 实时语音识别服务负载均衡失败,未获取到实时语音识别服务的IP地址。 | 检查VPC中的实时语音识别服务机器是否有异常。 |