全部产品
云市场
云游戏

接口说明

更新时间:2020-09-23 15:02:58

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

使用须知

  • 输入格式: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

交互流程

ASR

说明

  • 所有服务端的响应都会在返回信息的header包含表示本次识别任务的task_id参数,请记录该值,如果发生错误,请将task_id和错误信息提交到工单。

  • 交互流程图为Java SDK、C++ SDK、iOS SDK、Android SDK的交互流程,不包含RESTful API的交互流程,RESTful API的交互流程图请参见RESTFUL API

1. 鉴权

客户端与服务端建立WebSocket连接时,使用Token进行鉴权。关于Token获取请参见获取Token

2. 开始识别

客户端发起一句话识别请求,服务端确认请求有效。

其中在请求消息中需要进行参数设置,各参数由SDK中SpeechRecognizer对象的相关set方法设置,各参数含义如下。

参数

类型

是否必选

说明

appkey

String

管控台创建的项目appkey。

format

String

音频编码格式,默认值:PCM。

支持格式:PCM编码、16bit采样位数、单声道。

sample_rate

Integer

音频采样率,默认值:16000Hz。

根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。

enable_intermediate_result

Boolean

是否返回中间识别结果,默认值:False。

enable_punctuation_prediction

Boolean

是否在后处理中添加标点,默认值:False。

enable_inverse_text_normalization

Boolean

是否在后处理中执行ITN。设置为true时,中文数字将转为阿拉伯数字输出,默认值:False。

customization_id

String

自学习模型ID。

vocabulary_id

String

定制泛热词ID。

enable_voice_detection

Boolean

是否启动语音检测。默认值:False。

max_start_silence

Integer

当enabble_voice_detection设置为true时,该参数生效。表示允许的最大开始静音时长。取值范围:(0,60000]。单位:毫秒。

超出后(即开始识别后多时间没有检测到声音)服务端将会发送TaskFailed事件,结束本次识别。

max_end_silence

Integer

当enable_voice_detection设置为true时,该参数生效。表示允许的最大结束静音时长。单位:毫秒,取值范围:200ms~2000ms。

超出时长服务端会发送RecognitionCompleted事件,结束本次识别(需要注意后续的语音将不会进行识别)。

3. 发送数据

循环发送语音数据,持续接收识别结果。

  • 若enable_intermediate_result设置为true, 服务端会持续多次返回RecognitionResultChanged消息,即中间识别结果,示例如下:

    北京的天
    北京的天气

    服务端返回的响应消息:

    {
    	"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

    状态码,表示请求是否成功,见服务状态码。

    status_text

    String

    状态消息。

    task_id

    String

    任务全局唯一ID,请记录该值,便于排查问题。

    message_id

    String

    本次消息的ID。

    payload对象参数说明:

    参数

    类型

    说明

    result

    String

    中间识别结果。

    说明

    最后一次获取的中间识别结果与最终的识别的结果不一定相同,请以RecognitionCompleted消息的最终识别结果为准。

  • 若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

状态码,表示请求是否成功,见服务状态码。

status_text

String

状态消息。

task_id

String

任务全局唯一ID,请记录该值,便于排查问题。

message_id

String

本次消息的ID,由SDK自动生成。

payload对象参数说明:

参数

类型

说明

result

String

一句话识别的结果。

服务状态码

在服务的每一次响应中,都包含status字段,即服务状态码,此处列举通用错误码、网关错误码、配置错误码表格,其取值含义如下。

  • 通用错误码

    错误码

    原因

    解决办法

    40000001

    身份认证失败

    检查使用的令牌是否正确,是否过期。

    40000002

    无效的消息

    检查发送的消息是否符合要求。

    403

    令牌过期或无效的参数

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

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

    40000004

    空闲超时

    确认是否长时间(10秒)未发送数据到服务端。

    40000005

    请求数量过多

    检查是否超过了并发连接数或者每秒钟请求数。如果超过并发数,建议从免费版升级到商用版,或者商用版扩容并发资源。

    41050008

    采样率不匹配

    检查调用时设置的采样率和管控台上appkey绑定的ASR模型采样率是否一致。

    41010101

    不支持的采样率

    请发起调用时注意代码中设置的采样率参数(8000或16000)要与管控台上appkey对应的模型(8k或16k)匹配。

    41010120

    客户端超时错误

    客户端连续10秒及以上未发送数据,导致客户端超时错误。

    40000000

    默认的客户端错误码

    查看错误消息或提交工单。

    50000000

    默认的服务端错误

    如果偶现可以忽略,重复出现请提交工单。

    50000001

    内部调用错误

    如果偶现可以忽略,重复出现请提交工单。

    52010001

    内部调用错误

    如果偶现可以忽略,重复出现请提交工单。

  • 网关错误

    错误码

    原因

    解决办法

    40010001

    不支持的接口

    使用了不支持的接口,如果使用SDK请提交工单。

    40010002

    不支持的指令

    使用了不支持的指令,如果使用SDK请提交工单。

    40010003

    无效的指令

    指令格式错误,如果使用SDK请提交工单。

    40010004

    客户端提前断开连接

    检查是否在请求正常完成之前关闭了连接。

    40010005

    任务状态错误

    发送了当前任务状态不能处理的指令。

  • 配置错误

    错误码

    原因

    解决办法

    40020105

    应用不存在

    解析路由时找不到应用。

    40020106

    appkey和token不匹配

    检查应用apkey是否正确,是否与令牌归属同一个账号。

    40020503

    子账户鉴权失败

    使用父账户对调用的子账户授权POP API的访问权限。