全部产品
云市场

接口说明

更新时间:2019-10-11 13:58:27

功能介绍

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

  • 支持音频编码格式:pcm(无压缩的pcm文件或wav文件)、opus,16bit采样位数的单声道(mono);
  • 支持音频采样率:8000Hz、16000Hz;
  • 支持对返回结果进行设置:是否返回中间识别结果,是否在后处理中添加标点,是否将中文数字转为阿拉伯数字输出。
  • 支持多种语言的识别,可在控制台编辑项目中进行 模型选择

调用限制

  • 传入的语音数据不能超过60s

服务地址

访问类型 说明 URL
外网访问 所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL,不需您设置) wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1
阿里云上海ECS内网访问 您使用阿里云上海ECS(即ECS地域为华东2(上海)),可使用内网访问URL。
说明:使用内网访问方式,将不产生ECS实例的公网流量费用。
ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络后在其内部访问。
ws://nls-gateway.cn-shanghai-internal.aliyuncs.com/ws/v1

交互流程

说明:交互流程图为Java SDK、C++ SDK、iOS SDK、Android SDK的交互流程,不包含RESTful API的交互流程,RESTful API的交互流程图请直接阅读RESTful API 2.0一节。

ASR

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

0. 鉴权

客户端在与服务端建立WebSocket链接的时候,需要使用Token进行鉴权。Token获取请阅读 获取 Token

1. start and confirm

客户端发起一句话识别请求,服务端确认请求有效。其中在请求消息中需要进行参数设置,各参数由SDK中SpeechRecognizer对象的相关set方法设置,各参数含义如下:

参数 类型 是否必须 说明
appkey String 管控台创建的项目Appkey
format String 音频编码格式,默认是pcm;支持的格式:pcm(无压缩的pcm文件或wav文件)、opus,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 允许的最大开始静音,单位是毫秒,超出后(也即开始识别后多久没有声音)服务端将会发送TaskFailed事件,结束本次识别,需要先设置enabble_voice_detection为true
max_end_silence Integer 允许的最大结束静音,单位是毫秒,超出后服务端会发送RecognitionCompleted事件,结束本次识别(需要注意的是后续的语音不会继续进行识别),需要先设置enable_voice_detection为true,

2. send and recognize

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

  • 若enable_intermediate_result设置为 true, 服务端会持续多次返回RecognitionResultChanged消息,即中间识别结果,如:
  1. 北京的天
  2. 北京的天气

服务端返回的响应消息:

  1. {
  2. "header": {
  3. "namespace": "SpeechRecognizer",
  4. "name": "RecognitionResultChanged",
  5. "status": 20000000,
  6. "message_id": "e06d2b5d50ca40d5a50d4215c7c8d37c",
  7. "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
  8. "status_text": "Gateway:SUCCESS:Success."
  9. },
  10. "payload": {
  11. "result": "北京的天气"
  12. }
  13. }

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, 此步骤服务端不返回任何消息。

3. stop and complete

客户端发送停止一句话识别请求,通知服务端语音数据发送结束,停止语音识别,服务端返回最终识别结果:

  1. {
  2. "header": {
  3. "namespace": "SpeechRecognizer",
  4. "name": "RecognitionCompleted",
  5. "status": 20000000,
  6. "message_id": "10490c992aef44eaa4246614838fde86",
  7. "task_id": "4c3502c7a5ce4ac3bdc488749ce4f235",
  8. "status_text": "Gateway:SUCCESS:Success."
  9. },
  10. "payload": {
  11. "result": "北京的天气。"
  12. }
  13. }

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 无效的消息 检查发送的消息是否符合要求
40000003 令牌过期或无效的参数 首先检查使用的令牌是否过期,然后检查参数值设置是否合理
40000004 空闲超时 确认是否长时间没有发送数据掉服务端
40000005 请求数量过多 检查是否超过了并发连接数或者每秒钟请求数
40000000 默认的客户端错误码 查看错误消息或提交工单
50000000 默认的服务端错误 如果偶现可以忽略,重复出现请提交工单
50000001 内部调用错误 如果偶现可以忽略,重复出现请提交工单

网关错误:

错误码 原因 解决办法
40010001 不支持的接口 使用了不支持的接口,如果使用SDK请提交工单
40010002 不支持的指令 使用了不支持的指令,如果使用SDK请提交工单
40010003 无效的指令 指令格式错误,如果使用SDK请提交工单
40010004 客户端提前断开连接 检查是否在请求正常完成之前关闭了连接
40010005 任务状态错误 发送了当前任务状态不能处理的指令

Meta错误:

错误码 原因 解决办法
40020105 应用不存在 解析路由时找不到应用
40020106 appkey和token不匹配 检查应用apkey是否正确,是否与令牌归属同一个账号
40020503 子账户鉴权失败 使用父账户对调用的子账户授权POP api的访问权限