文档

接口说明

更新时间:
一键部署

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

使用须知

说明

如需使用Android/iOS SDK,请参见移动端接口说明

  • 支持的输入格式:单声道(mono)16bit采样位数音频,包括无压缩的PCM、WAV、OPUS、AMR、SPEEX、MP3、AAC格式。

  • 音频采样率:8000 Hz、16000 Hz。

  • 时长限制:语音数据时长不能超过60s。

  • 音频文件大小:不超过2 MB。

  • 设置返回结果:

    • 是否返回中间识别结果。

    • 是否在后处理中添加标点。

    • 是否将中文数字转为阿拉伯数字输出。

  • 设置多语言识别:在管控台编辑项目中进行模型选择,详情请参见管理项目

    目前支持的语种和方言模型如下:

    • 语种

      语言

      模型名称

      采样率

      标点

      ITN

      顺滑

      语义断句

      声音和文本对齐

      英语

      通用-英文,教育直播-英文,教育内容分析-英文

      16k

      支持

      支持

      支持

      不支持

      支持

      电话客服(通用)

      8k

      支持

      支持

      支持

      不支持

      不支持

      日语

      通用-日语

      16k

      支持

      支持

      不支持

      不支持

      支持

      西班牙语

      通用-西班牙语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      通用-西班牙客服通用

      8k

      支持

      支持

      不支持

      不支持

      不支持

      阿拉伯语

      通用-阿拉伯语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      哈萨克语

      通用-哈萨克语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      韩语

      通用-韩语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      泰语

      通用-泰语

      16k

      不支持

      不支持

      不支持

      不支持

      不支持

      通用-泰语客服通用

      8k

      不支持

      不支持

      不支持

      不支持

      不支持

      印尼语

      通用-印尼语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      电话客服(通用)

      8k

      支持

      支持

      不支持

      不支持

      不支持

      俄语

      通用-俄语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      越南语

      通用-越南语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      通用-越南语客服通用

      8k

      支持

      支持

      不支持

      不支持

      不支持

      法语

      通用-法语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      德语

      通用-德语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      意大利语

      通用-意大利语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      印地语

      通用-印地语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      马来语

      通用-马来语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      通用-马来语客服通用

      8k

      支持

      不支持

      不支持

      不支持

      不支持

      菲律宾语

      通用-菲律宾语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      电话客服(通用)

      8k

      支持

      支持

      不支持

      不支持

      不支持

      泰米尔语

      通用-泰米尔语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      葡萄牙语

      通用-葡萄牙语

      16k

      支持

      支持

      不支持

      不支持

      不支持

      土耳其语

      通用-土耳其语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      波兰语

      通用-波兰语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      乌克兰语

      通用-乌克兰语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      罗马尼亚语

      通用-罗马尼亚语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      荷兰语

      通用-荷兰语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      希腊语

      通用-希腊语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      匈牙利语

      通用-匈牙利语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      爪哇语

      通用-爪哇语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      孟加拉语

      通用-孟加拉语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      缅甸语

      通用-缅甸语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      老挝语

      通用-老挝语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      斯瓦希里语

      通用-斯瓦希里语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      阿塞拜疆语

      通用-阿塞拜疆语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      波斯语

      通用-波斯语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      僧伽罗语

      通用-僧伽罗语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      加泰罗尼亚语

      通用-加泰罗尼亚语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      高棉语

      通用-高棉语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      希伯来语

      通用-希伯来语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      克罗地亚语

      通用-克罗地亚语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      豪萨语

      通用-豪萨语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      马拉地语

      通用-马拉地语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      泰卢固语

      通用-泰卢固语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      旁遮普语

      通用-旁遮普语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      瑞典语

      通用-瑞典语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      保加利亚语

      通用-保加利亚语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      丹麦语

      通用-丹麦语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      挪威语

      通用-挪威语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      坎纳达语

      通用-坎纳达语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      马拉雅拉姆语

      通用-马拉雅拉姆语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      捷克语

      通用-捷克语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      乌尔都语

      通用-乌尔都语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      尼泊尔语

      通用-尼泊尔语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      蒙古语(外蒙)

      通用-蒙古语(外蒙)

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      乌兹别克语

      通用-乌兹别克语

      16k

      支持

      不支持

      不支持

      不支持

      不支持

    • 方言

      语言

      模型名称

      采样率

      标点

      ITN

      顺滑

      语义断句

      声音和文本对齐

      粤语

      通用-粤语

      16k

      支持

      支持

      支持

      不支持

      支持

      电话客服(通用)

      8k

      支持

      支持

      支持

      不支持

      支持

      粤中自由说

      8k

      支持

      支持

      支持

      不支持

      不支持

      粤语(繁体)

      通用-粤语(繁体)

      8k

      支持

      不支持

      不支持

      不支持

      不支持

      通用-粤语(繁体)

      16k

      支持

      不支持

      不支持

      不支持

      不支持

      四川话

      通用-四川话

      16k

      支持

      支持

      支持

      支持

      支持

      电话客服(通用)

      8k

      支持

      支持

      支持

      支持

      支持

      湖北话

      通用-湖北话

      16k

      支持

      支持

      支持

      支持

      支持

      通用-湖北话

      8k

      支持

      支持

      支持

      支持

      支持

      上海话

      通用-上海话

      16k

      支持

      支持

      支持

      支持

      不支持

      湖南话

      通用-湖南话

      16k

      支持

      支持

      支持

      支持

      支持

      河南话

      通用-河南话

      16k

      支持

      支持

      支持

      支持

      支持

      通用-河南话

      8k

      支持

      支持

      支持

      支持

      支持

      浙江话

      通用-浙江话

      16k

      支持

      支持

      支持

      支持

      不支持

      东北话

      通用-东北话

      16k

      支持

      支持

      支持

      支持

      支持

      山东话

      通用-山东话

      16k

      支持

      支持

      支持

      支持

      支持

      天津话

      通用-天津话

      16k

      支持

      支持

      支持

      支持

      支持

      陕西话

      通用-陕西话

      16k

      支持

      支持

      支持

      支持

      支持

      山西话

      通用-山西话

      16k

      支持

      支持

      支持

      支持

      支持

      贵州话

      通用-贵州话

      16k

      支持

      支持

      支持

      支持

      支持

      云南话

      通用-云南话

      16k

      支持

      支持

      支持

      支持

      支持

      甘肃话

      通用-甘肃话

      16k

      支持

      支持

      支持

      支持

      支持

      维吾尔语

      通用-维吾尔语

      16k

      不支持

      不支持

      不支持

      不支持

      不支持

      通用-维吾尔语

      8k

      不支持

      不支持

      不支持

      不支持

      不支持

      苏州话

      通用-苏州话

      16k

      支持

      支持

      支持

      支持

      不支持

      闽南语

      通用-闽南语

      16k

      支持

      支持

      支持

      支持

      不支持

      江西话

      通用-江西话

      16k

      支持

      支持

      支持

      支持

      支持

      宁夏话

      通用-宁夏话

      16k

      支持

      支持

      支持

      支持

      支持

      广西话

      通用-广西话

      16k

      支持

      支持

      支持

      支持

      支持

      通用-广西话

      8k

      支持

      支持

      支持

      支持

      支持

      中文地方口音

      电话客服(通用)

      8k

      支持

      支持

      支持

      支持

      支持

      中文普通话

      识音石 V1 - 端到端模型,教育内容分析,医疗内容分析,新闻媒体内容分析,娱乐视频内容分析,音视频离线转写(升级版),新零售领域识别模型,出行领域识别模型

      16k

      支持

      支持

      支持

      支持

      支持

      中英自由说

      16k

      支持

      支持

      支持

      支持

      不支持

      识音石 V1 - 端到端模型

      8k

      支持

      支持

      支持

      支持

      支持

就近地域智能接入

一句话识别支持就近地域智能接入,域名为nls-gateway.aliyuncs.com

推荐终端用户使用就近地域接入域名。根据调用接口时客户端所在的地理位置,系统会自动解析到最近的某个具体地域的服务器。例如在北京地域发起请求,系统会自动解析到北京地域的服务器,与指定域名nls-gateway-cn-beijing.aliyuncs.com实现效果一致。

服务地址

访问类型

说明

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实例的公网流量费用。

  • 关于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

交互流程

image
说明
  • 所有服务端的响应都会在返回信息的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

支持的输入格式:单声道(mono)16bit采样位数音频,包括无压缩的PCM、WAV、OPUS、AMR、SPEEX、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": "北京的天气。"
        }
}

header对象参数说明:

参数

类型

说明

namespace

String

消息所属的命名空间。

name

String

消息名称,RecognitionCompleted表示识别完成。

status

Integer

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

status_text

String

状态消息。

task_id

String

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

message_id

String

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

payload对象参数说明:

参数

类型

说明

result

String

一句话识别的结果。

服务状态码

在服务的每一次响应中,都包含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语音文件,且设置formatwav,请注意检查该语音文件的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进行正确设置。

41010104

TOO_LONG_SPEECH

发送的语音时长超过限制,仅在一句话识别接口上出现。

一句话语音识别支持60s以内的音频,如果超过60s,建议调用实时语音识别接口。

41010105

SILENT_SPEECH

纯静音数据或噪音数据,导致无法检测出任何有效语音。

无。

  • 本页导读 (1)
文档反馈