一句话识别功能支持对一分钟内的短语音进行识别，适用于对话聊天、控制口令、语音输入法、语音搜索等较短的语音识别场景。
使用须知
如需使用Android/iOS SDK，请参见移动端接口说明。
支持的输入格式：单声道（mono）、16 bit采样位数，包括PCM、PCM编码的WAV、OGG封装的OPUS、OGG封装的SPEEX、AMR、MP3、AAC。
音频采样率：8000 Hz、16000 Hz。
时长限制：语音数据时长不能超过60s。
音频文件大小：不超过2 MB。
支持情感分析：目前仅开放中文8k情感识别功能。
设置返回结果：
是否返回中间识别结果。
是否在后处理中添加标点。
是否将中文数字转为阿拉伯数字输出。
设置多语言识别：在管控台编辑项目中进行模型选择，详情请参见管理项目。
目前支持的语种和方言模型如下：
就近地域智能接入
一句话识别支持就近地域智能接入，域名为nls-gateway.aliyuncs.com。
推荐终端用户使用就近地域接入域名。根据调用接口时客户端所在的地理位置，系统会自动解析到最近的某个具体地域的服务器。例如在北京地域发起请求，系统会自动解析到北京地域的服务器，与指定域名nls-gateway-cn-beijing.aliyuncs.com实现效果一致。
服务地址
访问类型 | 说明 | URL |
外网访问（默认上海地域） | 所有服务器均可使用外网访问URL（SDK中默认设置了外网访问URL）。 |
|
ECS内网访问 | 使用阿里云上海、北京、深圳ECS（即ECS地域为华东2（上海）、华北2（北京）、华南1（深圳）），可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel，即不能在内网访问语音服务；如果希望使用AnyTunnel，需要创建专有网络在其内部访问。 重要
|
|
交互流程
所有服务端的响应都会在返回信息的header包含表示本次识别任务的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、WAV、OPUS、SPEEX、AMR、MP3、AAC。 |
sample_rate | Integer | 否 | 音频采样率，默认值：16000 Hz。 根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。 |
enable_intermediate_result | Boolean | 否 | 是否返回中间识别结果，默认值：False。 |
enable_punctuation_prediction | Boolean | 否 | 是否在后处理中添加标点，默认值：False。 |
enable_inverse_text_normalization | Boolean | 否 | ITN（逆文本inverse text normalization）中文数字转换阿拉伯数字。设置为True时，中文数字将转为阿拉伯数字输出，默认值：False。 |
disfluency | Boolean | 否 | 过滤语气词，即声音顺滑。默认值：False（关闭）。 |
customization_id | String | 否 | 自学习模型ID，具体可参见定制语言模型。 |
vocabulary_id | String | 否 | 定制泛热词ID，具体可参见在控制台创建热词。 |
enable_voice_detection | Boolean | 否 | 是否启动语音检测。开启后能够识别出一段音频中有效语音的开始和结束，剔除噪音数据。默认值：False（不开启）。 |
max_start_silence | Integer | 否 | 当enable_voice_detection设置为true时，该参数生效。表示允许的最大开始静音时长。建议取值范围：(0,60000]。单位：毫秒。 超出后（即开始识别后多时间没有检测到声音）服务端将会发送TaskFailed事件，结束本次识别。 |
max_end_silence | Integer | 否 | 当enable_voice_detection设置为true时，该参数生效。表示允许的最大结束静音时长。单位：毫秒，取值范围：200ms～6000ms。 超出时长服务端会发送RecognitionCompleted事件，结束本次识别（需要注意后续的语音将不会进行识别）。 |
audio_address | String | 否 | 可通过公网访问的音频文件下载链接。推荐使用阿里云OSS，具体请参见通过OSS如何获取访问URL。 |
special_word_filter | String（结构为JSON格式） | 否 | 敏感词过滤功能，支持开启或关闭，支持自定义敏感词。该参数可实现： 不处理（默认，即展示原文）、过滤、替换为*。 具体调用说明请见下文的自定义过滤词调用示例。 说明 开启但未配置敏感词，则会过滤默认词表：敏感词表。 |
自定义过滤词调用示例如下：
// 以实时转写为例，
JSONObject root = new JSONObject();
root.put("system_reserved_filter", true);
// 将以下词语替换成空
JSONObject root1 = new JSONObject();
JSONArray array1 = new JSONArray();
array1.add("开始");
array1.add("发生");
root1.put("word_list", array1);
// 将以下词语替换成*
JSONObject root2 = new JSONObject();
JSONArray array2 = new JSONArray();
array2.add("测试");
root2.put("word_list", array2);
// 可以全部设置，也可以部分设置
root.put("filter_with_empty", root1);
root.put("filter_with_signed", root2);
transcriber.addCustomedParam("special_word_filter", root);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": "北京的天气。",
"emo_tag": "neutral",
"emo_confidence": 0.931
}
}header对象参数说明：
参数 | 类型 | 说明 |
namespace | String | 消息所属的命名空间。 |
name | String | 消息名称，RecognitionCompleted表示识别完成。 |
status | Integer | 状态码，表示请求是否成功，见服务状态码。 |
status_text | String | 状态消息。 |
task_id | String | 任务全局唯一ID，请记录该值，便于排查问题。 |
message_id | String | 本次消息的ID，由SDK自动生成。 |
payload对象参数说明：
参数 | 类型 | 说明 |
result | String | 一句话识别的结果。 |
emo_tag | String | 当前句子的情感，包含positive(正面情感，如开心、满意）、negative(负面情感，如愤怒、沉闷、失望）、neutral (无明显情感）三种类别。 |
emo_confidence | Double | 当前句子识别情感的置信度，取值范围：[0.0,1.0]。值越大表示置信度越高。 |
服务状态码
在服务的每一次响应中，都包含status字段，即服务状态码，此处列举通用错误码、一句话识别错误码表格，其取值含义如下。
通用错误码
状态码 | 状态消息 | 原因 | 解决方案 |
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语音文件，且设置 |
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进行正确设置。 |
40270002 | NO_VALID_AUDIO_ERROR | 无效的音频。 | 从音频中没有识别出有效文本。 |
41010104 | TOO_LONG_SPEECH | 发送的语音时长超过限制，仅在一句话识别接口上出现。 | 一句话语音识别支持60s以内的音频，如果超过60s，建议调用实时语音识别接口。 |
41010105 | SILENT_SPEECH | 纯静音数据或噪音数据，导致无法检测出任何有效语音。 | 无。 |