阿里云首页 智能语音交互

接口说明

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

功能简介

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_log参数取值为true时,该目录用于保存中间音频文件。

save_wav

String

当初始化SDK时的save_log参数取值为true时,该参数生效。表示是否保存音频debug,该数据保存在debug目录中,需要确保debug_path有效可写。

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

enabble_voice_detection设置为true时,该参数生效。表示允许的最大开始静音时长。单位:毫秒。超出后(即开始识别后多长时间没有检测到声音)服务端将会发送TaskFailed事件,结束本次识别。

max_end_silence

Integer

enable_voice_detection设置为true时,该参数生效。表示允许的最大结束静音时长。单位:毫秒,取值范围:200ms~2000ms。超出时长服务端会发送RecognitionCompleted事件,结束本次识别(需要注意的是后续的语音不会继续进行识别)。

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

令牌过期或无效的参数

  1. 检查使用的令牌是否过期。

  2. 检查参数值设置是否合理。

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中的实时语音识别服务机器是否有异常。