一句话识别移动端SDK接口有哪些_智能语音交互(ISI)-阿里云帮助中心

对一分钟内的短语音进行识别，适用于对话聊天、控制口令、语音输入法、语音搜索等较短的语音识别场景。

功能简介

NUI SDK提供更小的工具包和更完善的状态管理。为满足不同用户需求，NUI SDK既能提供全链路的语音能力，同时可做原子能力SDK进行使用，并保持接口的统一。

使用须知

输入格式：PCM编码、16bit采样位数、单声道（mono）。
音频采样率：8000Hz/16000Hz。
时长限制：语音数据时长不能超过60s。
设置返回结果：是否返回中间识别结果、在后处理中添加标点、将中文数字转为阿拉伯数字输出。
设置多语言识别：在控制台编辑项目中进行模型选择，详情请参见模型选择。

服务地址

访问类型	说明	URL
外网访问（默认上海地域）	所有服务器均可使用外网访问URL（SDK中默认设置了外网访问URL）。	上海：`wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1` 北京：`wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1` 深圳：`wss://nls-gateway-cn-shenzhen.aliyuncs.com/ws/v1`
ECS内网访问	使用阿里云上海、北京、深圳ECS（即ECS地域为华东2（上海）、华北2（北京）、华南1（深圳）），可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel，即不能在内网访问语音服务；如果希望使用AnyTunnel，需要创建专有网络在其内部访问。重要使用内网访问方式，将不产生ECS实例的公网流量费用。关于ECS的网络类型请参见网络类型。	上海：`ws://nls-gateway-cn-shanghai-internal.aliyuncs.com:80/ws/v1` 北京：`ws://nls-gateway-cn-beijing-internal.aliyuncs.com:80/ws/v1` 深圳：`ws://nls-gateway-cn-shenzhen-internal.aliyuncs.com:80/ws/v1`

交互流程

下图展示iOS SDK、Android SDK的交互流程。

说明

服务端的响应除了音频流之外，都会在返回信息的header包含本次识别任务的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_log`参数取值为true时，该目录用于保存中间音频文件。
save_wav	String	否	当初始化SDK时的`save_log`参数取值为true时，该参数生效。表示是否保存音频debug，该数据保存在debug目录中，需要确保debug_path有效可写。

2. 开始识别

客户端发起一句话识别请求前需要进行参数设置，各参数由SDK中setParams接口以JSON格式设置，该参数只需设置一次。各参数含义如下。

参数	类型	是否必选	说明
app_key	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（逆文本inverse text normalization）中文数字转换阿拉伯数字。设置为True时，中文数字将转为阿拉伯数字输出，默认值：False。
customization_id	String	否	自学习模型ID。
vocabulary_id	String	否	定制泛热词ID。
enable_voice_detection	Boolean	否	是否启动语音检测。开启后能够识别出一段音频中有效语音的开始和结束，剔除噪音数据。默认值：False（不开启）。
max_start_silence	Integer	否	当`enable_voice_detection`设置为true时，该参数生效。表示允许的最大开始静音时长。单位：毫秒。超出后（即开始识别后多长时间没有检测到声音）服务端将会发送TaskFailed事件，结束本次识别。
max_end_silence	Integer	否	当`enable_voice_detection`设置为true时，该参数生效。表示允许的最大结束静音时长。单位：毫秒，取值范围：200ms～6000ms。超出时长服务端会发送RecognitionCompleted事件，结束本次识别（需要注意的是后续的语音不会继续进行识别）。
extend_config	JsonObject	否	若需要设置交互协议支持但是接口说明中未说明的参数，可通过此万能设置接口进行配置。具体设置方法请见代码示例。

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	一句话识别最终结果。

错误码

通用错误码

状态码	状态消息	原因	解决方案
40000000	默认的客户端错误码，对应了多个错误消息。	用户使用了不合理的参数或者调用逻辑。	请参考官网文档示例代码进行对比测试验证。
40000001	The token 'xxx' has expired； The token 'xxx' is invalid	用户使用了不合理的参数或者调用逻辑。通用客户端错误码，通常是涉及Token相关的不正确使用，例如Token过期或者非法。	请参考官网文档示例代码进行对比测试验证。
40000002	Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!	无效或者错误的报文消息。	请参考官网文档示例代码进行对比测试验证。
40000003	PARAMETER_INVALID; Failed to decode url params	用户传递的参数有误，一般常见于RESTful接口调用。	请参考官网文档示例代码进行对比测试验证。
40000005	Gateway:TOO_MANY_REQUESTS:Too many requests!	并发请求过多。	如果是试用版调用，建议您升级为商用版本以增大并发。如果已是商用版，可购买并发资源包，扩充您的并发额度。
40000009	Invalid wav header!	错误的消息头。	如果您发送的是WAV语音文件，且设置`format`为`wav`，请注意检查该语音文件的WAV头是否正确，否则可能会被服务端拒绝。
40000009	Too large wav header!	传输的语音WAV头不合法。	建议使用PCM、OPUS等格式发送音频流，如果是WAV，建议关注语音文件的WAV头信息是否为正确的数据长度大小。
40000010	Gateway:FREE_TRIAL_EXPIRED:The free trial has expired!	试用期已结束，并且未开通商用版、或账号欠费。	请登录控制台确认服务开通状态以及账户余额。
40010001	Gateway:NAMESPACE_NOT_FOUND:RESTful url path illegal	不支持的接口或参数。	请检查调用时传递的参数内容是否和官网文档要求的一致，并结合错误信息对比排查，设置为正确的参数。比如您是否通过curl命令执行RESTful接口请求，拼接的URL是否合法。
40010003	Gateway:DIRECTIVE_INVALID:[xxx]	客户端侧通用错误码。	表示客户端传递了不正确的参数或指令，在不同的接口上有对应的详细报错信息，请参考对应文档进行正确设置。
40010004	Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!	在请求处理完成前客户端主动结束。	无，或者请在服务端响应完成后再关闭链接。
40010005	Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!	客户端发送了当前不支持的消息指令。	请参考官网文档示例代码进行对比测试验证。
40020105	Meta:APPKEY_NOT_EXIST:Appkey not exist!	使用了不存在的Appkey。	请确认是否使用了不存在的Appkey，Appkey可以通过登录控制台后查看项目配置。
40020106	Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!	调用时传递的Appkey和Token并非同一个账号UID所创建，导致不匹配。	请检查是否存在两个账号混用的情况，避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。
403	Forbidden	使用的Token无效，例如Token不存在或者已过期。	请设置正确的Token。Token存在有效期限制，请及时在过期前获取新的Token。
41000003	MetaInfo doesn't have end point info	无法获取该Appkey的路由信息。	请检查是否存在两个账号混用的情况，避免使用账号A名下的Appkey和账号B名下生成的Token搭配使用。
41010101	UNSUPPORTED_SAMPLE_RATE	不支持的采样率格式。	当前实时语音识别只支持8000 Hz和16000 Hz两种采样率格式的音频。
41040201	Realtime:GET_CLIENT_DATA_TIMEOUT:Client data does not send continuously!	获取客户端发送的数据超时失败。	客户端在调用实时语音识别时请保持实时速率发送，发送完成后及时关闭链接。
50000000	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。
50000001	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。
52010001	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。

一句话识别错误码

状态码	状态消息	原因	解决方案
40000000	Gateway:CLIENT_ERROR:Empty audio data!	没有音频数据。	建议参考公共云示例代码，请求时发送音频数据。
40000004	Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time	请求建立链接后，长时间没有发送任何数据，超过10s后服务端会返回此错误信息。	请在建立链接后和服务端保持交互，比如持续发送语音流，您可以在采集音频的同时进行发送，发送结束后及时关闭链接。
40010002	Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!	发送了服务端不支持的消息指令。	请参考官网文档示例代码进行对比测试验证。
40010003	Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)	热词数量设置过多。	请参考API进行正确设置。
41010104	TOO_LONG_SPEECH	发送的语音时长超过限制，仅在一句话识别接口上出现。	一句话语音识别支持60s以内的音频，如果超过60s，建议调用实时语音识别接口。
41010105	SILENT_SPEECH	纯静音数据或噪音数据，导致无法检测出任何有效语音。	无。

一句话识别/实时语音识别/录音文件识别极速版

配置或参数错误

状态码	状态消息	原因	解决方案
240999	DEFAULT_ERROR	内部默认错误。	内部未明确错误。
240001	NUI_CONFIG_INVALID	配置文件错误。	配置文件错误，请确认传入的资源路径内是否有资源文件。如果是Android平台，请参考代码样例主动使用copyAssets接口。
240002	ILLEGAL_PARAM	非法参数。	请确认传入的格式是否正确，包括字段类型、值范围限制。例如enable_voice_detection需要设置成bool类型的true，而不是1或者字符串"true"。
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内部状态错误。	请阅读SDK流程图，确认是否在错误状态下调用接口。
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
本地引擎初始化失败。
请确认本地引擎的模型是否有效、目录是否可读写。

音频错误

状态码	状态消息	原因	解决方案
240051	UPDATE_AUDIO_ERROR	推送音频错误，一般为输入音频长度大于所需音频。	确认推送的音频长度是否非法。
240052	MIC_ERROR	连续2s未获取到音频。	请确认在音频数据回调中是否正确提供所需长度的音频。

网络错误

状态码	状态消息	原因	解决方案
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_secret，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	文件转写服务错误。	请参考服务端错误码进一步定位。

状态码	状态消息	原因	解决方案
240040	CEI_INIT_FAIL	本地引擎初始化失败。	请确认本地引擎的模型是否有效、目录是否可读写。