一句话识别接口说明 - 智能语音交互

一句话识别将 60 秒以内的短语音转换为文本，适用于对话聊天、控制口令、语音输入法和语音搜索等场景。客户端通过 WebSocket 发送音频流，接收识别事件和结果。

使用须知

音频编码和请求参数必须一致，否则可能导致识别失败或结果为空。

声道和采样位数：单声道、16 bit。
音频格式：PCM、PCM 编码的 WAV、OGG 封装的 OPUS、OGG 封装的 SPEEX、AMR。
采样率：8000 Hz 或 16000 Hz。项目模型必须支持音频所用的采样率和语言。
音频时长：不超过 60 秒。
音频大小：不超过 2 MB。

通过请求参数可配置中间结果、标点和逆文本正则化（ITN）等功能。

选择识别模型

语种和方言模型不能通过请求参数指定。在智能语音交互控制台的全部项目页面，找到目标项目，单击项目功能配置，选择与音频语言和采样率匹配的模型。配置方法请参见管理项目。

可选模型以项目功能配置页面为准。先选择采样率，再选择对应的语言模型。

服务地址

通过公网使用以下 WebSocket 地址：wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1。

交互流程

以下流程适用于 WebSocket 及基于该协议的 SDK。RESTful API 的调用方式，请参见RESTful API。

所有服务端事件的 header 均包含本次识别任务的 task_id，可用于关联请求、响应和排查问题。

1. 鉴权

客户端建立 WebSocket 连接时，使用 NLS Token 进行鉴权。

Token 的获取方法，请参见获取 Token。

2. 开始识别

客户端发送 StartRecognition 指令并设置识别参数。服务端确认请求有效后，返回 RecognitionStarted 事件。收到该事件后再发送音频数据。

3. 发送数据

客户端分块发送二进制音频数据，同时接收服务端事件。

enable_intermediate_result 为 true 时，服务端可多次返回 RecognitionResultChanged 中间结果。
enable_intermediate_result 为 false 时，不返回中间结果。服务端仍可能返回 RecognitionCompleted 或 TaskFailed，客户端需要持续处理这些事件。

重要
最后一次中间结果可能与最终结果不同，以 RecognitionCompleted 中的结果为准。

4. 结束识别

音频发送完毕后，客户端发送 StopRecognition 指令。正常完成时，服务端返回 RecognitionCompleted 和最终结果；请求失败时返回 TaskFailed。等待服务端结束事件后再关闭连接。

开启语音检测后，结束静音时长超过 max_end_silence 时，服务端可提前完成识别，后续音频不再识别。

请求参数

SDK 通过 SpeechRecognizer 对象提供的方法设置参数。直接使用 WebSocket 时，appkey 位于请求的 header 中，其余识别参数位于 StartRecognition 的 payload 中。

参数	类型	是否必选	说明
appkey	String	是	在控制台创建的项目 Appkey。
format	String	否	音频格式：`pcm`、`wav`、`opus`、`speex`、`amr`。WAV 使用 PCM 编码，OPUS 和 SPEEX 使用 OGG 封装。
sample_rate	Integer	否	音频采样率，单位为 Hz，默认值为 `16000`。取值为 `8000` 或 `16000`，必须与音频及项目模型匹配。
enable_intermediate_result	Boolean	否	是否返回中间识别结果，默认值为 `false`。
enable_punctuation_prediction	Boolean	否	是否在后处理中添加标点，默认值为 `false`。
enable_inverse_text_normalization	Boolean	否	是否开启逆文本正则化（ITN）。设置为 `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` 时生效。允许的最大结束静音时长，单位为毫秒，取值范围为 200～6000。结束静音时长超过该值时，服务端返回 `RecognitionCompleted` 并结束识别，后续音频不再识别。

响应事件

header 的通用字段如下。

参数	类型	说明
namespace	String	命名空间，取值为 `SpeechRecognizer`。
name	String	事件名称，见下方各事件说明。
status	Integer	状态码，`20000000` 表示成功，其他取值见服务状态码。
status_text	String	状态消息。
task_id	String	本次识别任务的全局唯一 ID，与客户端请求中的任务 ID 对应。记录该值以便排查问题。
message_id	String	本条服务端响应消息的 ID。

RecognitionStarted

服务端已接受开始识别请求，可以发送音频数据。该事件不包含识别结果。

RecognitionResultChanged

返回中间识别结果，payload.result 为 String 类型。仅在 enable_intermediate_result 为 true 时返回。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionResultChanged",
    "status": 20000000,
    "message_id": "f2bc60c1fd834da1bef7b9929fd1****",
    "task_id": "7ce7bac115844c109c680da4bf28****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "开始测试今天北京的天气很好我想购买三十二个苹果请拨打电话一二三四五结束测试"
  }
}

RecognitionCompleted

识别正常完成，payload.result 为 String 类型，表示最终结果。

{
  "header": {
    "namespace": "SpeechRecognizer",
    "name": "RecognitionCompleted",
    "status": 20000000,
    "message_id": "22ac941179bf45a8989d660bd9e8****",
    "task_id": "7ce7bac115844c109c680da4bf28****",
    "status_text": "Gateway:SUCCESS:Success."
  },
  "payload": {
    "result": "开始测试今天北京的天气很好我想购买三十二个苹果请拨打电话一二三四五结束测试"
  }
}

TaskFailed

识别任务失败。根据 header.status 和 header.status_text 排查原因。例如，未发送音频数据就结束请求，会返回 40000000 和 Gateway:CLIENT_ERROR:Empty audio data!。

服务状态码

结合 status 和 status_text 判断错误。同一状态码可能对应不同原因，应以具体状态消息为准。

通用错误码

状态码	状态消息	原因	解决方案
40000000	默认的客户端错误码，对应了多个错误消息。	使用了不合理的参数或调用逻辑。	检查请求参数、指令顺序及具体状态消息。
40000001	The token 'xxx' has expired； The token 'xxx' is invalid	Token 过期或无效。	获取有效的 NLS Token 后重新调用。
40000002	Gateway:MESSAGE_INVALID:Can't process message in state'FAILED'!	消息无效，或当前任务状态不接受该消息。	检查消息结构和指令顺序。任务失败后重新发起识别。
40000003	PARAMETER_INVALID; Failed to decode url params	参数无效。	检查参数名称、类型和值是否符合接口要求。
40000005	Gateway:TOO_MANY_REQUESTS:Too many requests!	并发请求过多。	降低同时进行的请求数，并检查可用并发额度。
40000009	Invalid wav header!	错误的消息头。	如果发送的是WAV语音文件，且设置`format`为`wav`，检查该语音文件的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	使用了不支持的接口或参数。	检查服务地址、命名空间和参数是否符合接口要求。
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。
40020106	Meta:APPKEY_UID_MISMATCH:Appkey and user mismatch!	Appkey 与 Token 不属于同一账号。	使用同一账号的项目 Appkey 和 NLS Token。
403	Forbidden	Token 不存在、过期或无效。	使用有效的 NLS Token，并在过期前获取新 Token。
41000003	MetaInfo doesn't have end point info	无法获取 Appkey 的路由信息。	检查 Appkey，并确认 Appkey 与 Token 所属账号一致。
41010101	UNSUPPORTED_SAMPLE_RATE	采样率不受当前配置支持。	确认音频采样率为 8000 Hz 或 16000 Hz，且与请求参数及项目模型匹配。
50000000	GRPC_ERROR:Grpc error!	服务端调用异常，可能与负载或网络有关。	重试请求；如问题持续存在，联系技术支持并提供 task_id。
50000001	GRPC_ERROR:Grpc error!	服务端调用异常，可能与负载或网络有关。	重试请求；如问题持续存在，联系技术支持并提供 task_id。
52010001	GRPC_ERROR:Grpc error!	服务端调用异常，可能与负载或网络有关。	重试请求；如问题持续存在，联系技术支持并提供 task_id。

一句话识别错误码

状态码	状态消息	原因	解决方案
40000000	Gateway:CLIENT_ERROR:Empty audio data!	未发送音频数据。	发送非空的二进制音频数据，再发送停止指令。
40000004	Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time	WebSocket 连接建立后，长时间未发送数据，空闲超过 10 秒。	建立连接后及时发送识别指令和音频数据，音频发送完毕后及时发送停止指令。
40010002	Gateway:DIRECTIVE_NOT_SUPPORTED:Directive'SpeechRecognizer.EnhanceRecognition'isnotsupported!	发送了服务端不支持的指令。	检查指令名称，使用一句话识别接口支持的指令。
40010003	Gateway:DIRECTIVE_INVALID:Too many items for ‘vocabulary'!(173)	热词数量过多。	按所用热词配置方式的数量限制调整热词。
40270002	NO_VALID_AUDIO_ERROR	音频无效，未识别出有效文本。	检查音频是否包含清晰语音，以及编码、采样率和模型是否匹配。
41010104	TOO_LONG_SPEECH	音频时长超过一句话识别限制。	使用 60 秒以内的音频；较长语音使用实时语音识别接口。
41010105	SILENT_SPEECH	静音或噪音导致未检测到有效语音。	检查音频内容；若开启语音检测，检查开始静音时长设置。