一句话识别接口说明-智能语音交互(ISI)-阿里云帮助中心

计费和并发限制

一句话识别提供试用版和商用版。计费项目请参见计费项；计费方式及升级流程请参见计费方式。

并发额度及调整方式，请参见并发与 QPS。

使用须知

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

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

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

情感分析仅适用于中文 8 kHz 情感识别模型。

说明

Android 和 iOS SDK 的使用方法，请参见移动端接口说明。

选择识别模型

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

语种和方言模型

下表列出语种、方言模型及其能力。功能是否生效还取决于所用接口和模型。

语种

语言	模型名称	采样率	标点	ITN	顺滑	语义断句	声音和文本对齐
英语	通用-英文，教育直播-英文，教育内容分析-英文	16 kHz	支持	支持	支持	不支持	支持
	电话客服（通用）	8 kHz	支持	支持	支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
日语	通用-日语	16 kHz	支持	支持	不支持	不支持	支持
西班牙语	通用-西班牙语	16 kHz	支持	支持	不支持	不支持	不支持
西班牙语	通用-西班牙客服通用	8 kHz	支持	支持	不支持	不支持	不支持
阿拉伯语	通用-阿拉伯语	16 kHz	支持	不支持	不支持	不支持	不支持
哈萨克语	通用-哈萨克语	16 kHz	支持	不支持	不支持	不支持	不支持
韩语	通用-韩语	16 kHz	支持	支持	不支持	不支持	不支持
泰语	通用-泰语	16 kHz	不支持	不支持	不支持	不支持	不支持
	通用-泰语客服通用	8 kHz	不支持	不支持	不支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
印尼语	通用-印尼语	16 kHz	支持	支持	不支持	不支持	不支持
	电话客服（通用）	8 kHz	支持	支持	不支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
俄语	通用-俄语	16 kHz	支持	支持	不支持	不支持	不支持
越南语	通用-越南语	16 kHz	支持	支持	不支持	不支持	不支持
	通用-越南语客服通用	8 kHz	支持	支持	不支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
法语	通用-法语	16 kHz	支持	支持	不支持	不支持	不支持
德语	通用-德语	16 kHz	支持	支持	不支持	不支持	不支持
意大利语	通用-意大利语	16 kHz	支持	不支持	不支持	不支持	不支持
印地语	通用-印地语	16 kHz	支持	不支持	不支持	不支持	不支持
马来语	通用-马来语	16 kHz	支持	不支持	不支持	不支持	不支持
	通用-马来语客服通用	8 kHz	支持	不支持	不支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
菲律宾语	通用-菲律宾语	16 kHz	支持	支持	不支持	不支持	不支持
	电话客服（通用）	8 kHz	支持	支持	不支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
泰米尔语	通用-泰米尔语	16 kHz	支持	不支持	不支持	不支持	不支持
葡萄牙语	通用-葡萄牙语	16 kHz	支持	支持	不支持	不支持	不支持
土耳其语	通用-土耳其语	16 kHz	支持	不支持	不支持	不支持	不支持
波兰语	通用-波兰语	16 kHz	支持	不支持	不支持	不支持	不支持
乌克兰语	通用-乌克兰语	16 kHz	支持	不支持	不支持	不支持	不支持
罗马尼亚语	通用-罗马尼亚语	16 kHz	支持	不支持	不支持	不支持	不支持
荷兰语	通用-荷兰语	16 kHz	支持	不支持	不支持	不支持	不支持
希腊语	通用-希腊语	16 kHz	支持	不支持	不支持	不支持	不支持
匈牙利语	通用-匈牙利语	16 kHz	支持	不支持	不支持	不支持	不支持
爪哇语	通用-爪哇语	16 kHz	支持	不支持	不支持	不支持	不支持
孟加拉语	通用-孟加拉语	16 kHz	支持	不支持	不支持	不支持	不支持
缅甸语	通用-缅甸语	16 kHz	支持	不支持	不支持	不支持	不支持
老挝语	通用-老挝语	16 kHz	支持	不支持	不支持	不支持	不支持
斯瓦希里语	通用-斯瓦希里语	16 kHz	支持	不支持	不支持	不支持	不支持
阿塞拜疆语	通用-阿塞拜疆语	16 kHz	支持	不支持	不支持	不支持	不支持
波斯语	通用-波斯语	16 kHz	支持	不支持	不支持	不支持	不支持
僧伽罗语	通用-僧伽罗语	16 kHz	支持	不支持	不支持	不支持	不支持
加泰罗尼亚语	通用-加泰罗尼亚语	16 kHz	支持	不支持	不支持	不支持	不支持
高棉语	通用-高棉语	16 kHz	支持	不支持	不支持	不支持	不支持
希伯来语	通用-希伯来语	16 kHz	支持	不支持	不支持	不支持	不支持
克罗地亚语	通用-克罗地亚语	16 kHz	支持	不支持	不支持	不支持	不支持
豪萨语	通用-豪萨语	16 kHz	支持	不支持	不支持	不支持	不支持
马拉地语	通用-马拉地语	16 kHz	支持	不支持	不支持	不支持	不支持
泰卢固语	通用-泰卢固语	16 kHz	支持	不支持	不支持	不支持	不支持
旁遮普语	通用-旁遮普语	16 kHz	支持	不支持	不支持	不支持	不支持
瑞典语	通用-瑞典语	16 kHz	支持	不支持	不支持	不支持	不支持
保加利亚语	通用-保加利亚语	16 kHz	支持	不支持	不支持	不支持	不支持
丹麦语	通用-丹麦语	16 kHz	支持	不支持	不支持	不支持	不支持
挪威语	通用-挪威语	16 kHz	支持	不支持	不支持	不支持	不支持
坎纳达语	通用-坎纳达语	16 kHz	支持	不支持	不支持	不支持	不支持
马拉雅拉姆语	通用-马拉雅拉姆语	16 kHz	支持	不支持	不支持	不支持	不支持
捷克语	通用-捷克语	16 kHz	支持	不支持	不支持	不支持	不支持
乌尔都语	通用-乌尔都语	16 kHz	支持	不支持	不支持	不支持	不支持
尼泊尔语	通用-尼泊尔语	16 kHz	支持	不支持	不支持	不支持	不支持
蒙古语（外蒙）	通用-蒙古语（外蒙）	16 kHz	支持	不支持	不支持	不支持	不支持
乌兹别克语	通用-乌兹别克语	16 kHz	支持	不支持	不支持	不支持	不支持

方言

语言	模型名称	采样率	标点	ITN	顺滑	语义断句	声音和文本对齐
粤语	通用-粤语	16 kHz	支持	支持	支持	不支持	支持
	电话客服（通用）	8 kHz	支持	支持	支持	不支持	支持
	粤中自由说	8 kHz	支持	支持	支持	不支持	不支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持
粤语（繁体）	通用-粤语（繁体）	8 kHz	支持	不支持	不支持	不支持	不支持
粤语（繁体）	通用-粤语（繁体）	16 kHz	支持	不支持	不支持	不支持	不支持
四川话	通用-四川话	16 kHz	支持	支持	支持	支持	支持
四川话	电话客服（通用）	8 kHz	支持	支持	支持	支持	支持
湖北话	通用-湖北话	16 kHz	支持	支持	支持	支持	支持
湖北话	通用-湖北话	8 kHz	支持	支持	支持	支持	支持
上海话	通用-上海话	16 kHz	支持	支持	支持	支持	不支持
湖南话	通用-湖南话	16 kHz	支持	支持	支持	支持	支持
河南话	通用-河南话	16 kHz	支持	支持	支持	支持	支持
河南话	通用-河南话	8 kHz	支持	支持	支持	支持	支持
浙江话	通用-浙江话	16 kHz	支持	支持	支持	支持	不支持
东北话	通用-东北话	16 kHz	支持	支持	支持	支持	支持
山东话	通用-山东话	16 kHz	支持	支持	支持	支持	支持
天津话	通用-天津话	16 kHz	支持	支持	支持	支持	支持
陕西话	通用-陕西话	16 kHz	支持	支持	支持	支持	支持
山西话	通用-山西话	16 kHz	支持	支持	支持	支持	支持
贵州话	通用-贵州话	16 kHz	支持	支持	支持	支持	支持
云南话	通用-云南话	16 kHz	支持	支持	支持	支持	支持
甘肃话	通用-甘肃话	16 kHz	支持	支持	支持	支持	支持
维吾尔语	通用-维吾尔语	16 kHz	不支持	不支持	不支持	不支持	不支持
维吾尔语	通用-维吾尔语	8 kHz	不支持	不支持	不支持	不支持	不支持
苏州话	通用-苏州话	16 kHz	支持	支持	支持	支持	不支持
闽南语	通用-闽南语	16 kHz	支持	支持	支持	支持	不支持
江西话	通用-江西话	16 kHz	支持	支持	支持	支持	支持
宁夏话	通用-宁夏话	16 kHz	支持	支持	支持	支持	支持
广西话	通用-广西话	16 kHz	支持	支持	支持	支持	支持
广西话	通用-广西话	8 kHz	支持	支持	支持	支持	支持
中文普通话	识音石 V1 - 端到端模型，教育内容分析，医疗内容分析，新闻媒体内容分析，娱乐视频内容分析，音视频离线转写（升级版），新零售领域识别模型，出行领域识别模型，汽车领域	16 kHz	支持	支持	支持	支持	支持
	中英自由说	16 kHz	支持	支持	支持	支持	不支持
	识音石 V1 - 端到端模型	8 kHz	支持	支持	支持	支持	支持
	东南亚多语言	16 kHz	支持	不支持	不支持	不支持	不支持

服务地址

访问类型	说明	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实例的公网流量费用。	上海：`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`

就近地域智能接入

一句话识别支持使用 nls-gateway.aliyuncs.com 就近接入。系统根据客户端的地理位置，将域名解析到就近地域的服务器。例如，在北京发起请求时，解析到北京地域的服务器，与使用 nls-gateway-cn-beijing.aliyuncs.com 的效果一致。

交互流程

以下流程适用于 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`。还支持 `mp3` 和 `aac`。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` 并结束识别，后续音频不再识别。
special_word_filter	Object（JSON 对象）	否	自定义过滤词配置，过滤词总数不超过 32 个。支持将匹配词替换为空或 `*`。具体结构见下方自定义过滤词示例。
enable_multi_thresh_mod	Boolean	否	仅在 `enable_voice_detection` 为 `true` 时生效。设置为 `true` 可避免语音检测（VAD）生成过长的语音片段；默认值为 `false`（关闭）。

如需通过音频文件 URL 发起识别，请使用RESTful API。

自定义过滤词

special_word_filter 是 JSON 对象，不是序列化后的 JSON 字符串。自定义词总数不超过 32 个。filter_with_empty 将匹配词替换为空，filter_with_signed 将匹配词替换为 *；两个字段可单独或同时设置。

以下为 StartRecognition 请求中的 payload 片段，用于过滤中文识别结果中的词语：

{
  "format": "pcm",
  "sample_rate": 16000,
  "special_word_filter": {
    "filter_with_empty": {
      "word_list": ["北京"]
    },
    "filter_with_signed": {
      "word_list": ["测试", "苹果"]
    }
  }
}

响应事件

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": "开始测试今天北京的天气很好我想购买三十二个苹果请拨打电话一二三四五结束测试"
  }
}

使用中文 8 kHz 情感识别模型时，结果还包含以下字段。普通识别模型不保证返回这些字段。

参数	类型	说明
emo_tag	String	当前句子的情感：`positive`（正面，如开心、满意）、`negative`（负面，如愤怒、沉闷、失望）、`neutral`（无明显情感）。
emo_confidence	Double	情感识别置信度，取值范围为 [0.0, 1.0]，值越大表示置信度越高。

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	静音或噪音导致未检测到有效语音。	检查音频内容；若开启语音检测，检查开始静音时长设置。