文档

接口说明

更新时间:
一键部署

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

功能简介

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的交互流程。

image

说明

服务端的响应除了音频流之外,都会在返回信息的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格式设置,该参数只需设置一次。各参数含义如下。

参数

类型

是否必选

说明

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(逆文本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事件,结束本次识别(需要注意的是后续的语音不会继续进行识别)。

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语音文件,且设置formatwav,请注意检查该语音文件的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

    非法参数。

    请确认传入的格式是否正确,包括字段类型、值范围限制。

    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

    文件转写服务错误。

    请参考服务端错误码进一步定位。

  • 本页导读 (1)
文档反馈