接口说明-阿里云帮助中心

支持通过关键词进行语音唤醒并进入语音识别，适用于语音助手类场景。默认模型唤醒词为“小云小云”。

使用须知

输入格式：PCM编码、16 bit采样位数、单声道（mono）。
音频采样率：8000 Hz、16000 Hz。
时长限制：识别语音数据时长不能超过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参数。如果使用过程中出现异常错误，请加入钉钉群21295019391，并提供task_id和错误信息给产品技术人员进行定位排查。

1.鉴权和初始化

初始化时需要进行鉴权，通过鉴权后才可以使用语音服务。鉴权流程在SDK内部完成，在初始化时需要传入相关参数。SDK内部在鉴权成功后，会自动获得Token用于识别服务的访问。

参数	类型	是否必须	说明
ak_id	String	是	阿里云AccessKey ID，用于鉴权。更多信息，请参见准备账号。
ak_secret	String	是	阿里云AccessKey Secret ，用于鉴权。更多信息，请参见准备账号。
app_key	String	是	智能语音交互控制台创建项目的Appkey。
sdk_code	String	是	SDK售卖码。
device_id	String	是	设备标识，唯一标识一台设备（如Mac地址/SN/UniquePsuedoID），请确保设备唯一，否则将可能导致鉴权失败。
workspace	String	是	工作目录路径，SDK从该路径读取配置文件。
debug_path	String	否	debug目录，当初始化SDK时的save_log参数取值为true时，该目录用于保存中间音频文件。
save_wav	String	否	当初始化SDK时的save_log参数取值为true时，该参数生效。表示是否保存音频debug，该数据保存在debug目录中，需要确保debug_path有效可写。
upgrade_file	String	否	如果需要使用语音唤醒功能，可以通过该参数设置唤醒模型的目录。

2.开始唤醒识别检测

在客户端发起唤醒识别请求前需要进行参数设置，各参数由SDK中setParams接口以JSON格式设置，该参数设置一次即可。

参数	类型	是否必须	说明
service_type	Int	是	需要请求的语音服务类型，一句话识别为0。
direct_ip	String	否	支持客户端自行DNS解析后传入IP进行访问。
nls_config	JsonObject	否	访问语音服务相关的参数配置，详情请参见下表。
wuw	JsonArray	否	自定义唤醒词，用于添加唤醒词进行唤醒检测，例如： `"wuw":[` `{"name":"小白小白","type":"main"},` `{"name":"小黑小黑","type":"action"}` `]` 可以添加多个词进行唤醒，name为唤醒词内容，type为唤醒词类型，支持主唤醒词main和命令词action。

其中，nls_config参数配置如下：

参数	类型	是否必须	说明
sr_format	String	否	音频编码格式，支持OPUS编码和PCM原始音频。默认值：OPUS。说明如果使用8000 Hz采样率，则只支持PCM格式。
sample_rate	Integer	否	音频采样率，默认值：16000 Hz。根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。
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	否	当enabble_voice_detection设置为true时，该参数生效。表示允许的最大开始静音时长。单位：毫秒。超出后（即开始识别后多长时间没有检测到声音）服务端将会发送TaskFailed事件，结束本次识别。
max_end_silence	Integer	否	当enable_voice_detection设置为true时，该参数生效。表示允许的最大结束静音时长。单位：毫秒，取值范围：200ms～2000ms。超出时长服务端会发送RecognitionCompleted事件，结束本次识别（需要注意后续的语音将不会进行识别）。

3.检测到唤醒词

如果检测到语音唤醒词，SDK会上报EVENT_WUW_TRUST事件。

4.获取中间结果

在唤醒后，如果检测到人声，SDK会循环发送语音数据，持续接收识别结果。

若enable_intermediate_result设置为true，SDK会持续多次通过onNuiEventCallback回调上报EVENT_ASR_PARTIAL_RESULT事件，即中间识别结果。

{
    "header": {
        "namespace": "SpeechRecognizer",
        "name": "RecognitionResultChanged",
        "status": 20000000,
        "message_id": "e06d2b5d50ca40d5a50d4215c7c8d37c",
        "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
        "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	中间识别结果。

若enable_intermediate_result设置为false，此步服务端不返回任何消息。

5.识别结束

如果检测到语音结束，SDK会自动通知服务端语音数据发送结束，停止语音识别，服务端返回最终识别结果如下：

{
    "header": {
        "namespace": "SpeechRecognizer",
        "name": "RecognitionCompleted",
        "status": 20000000,
        "message_id": "10490c992aef44eaa4246614838fde86",
        "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
        "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	一句话识别最终结果。

错误码

请参见一句话识别错误码。