接口说明
对长时间的语音数据流进行识别,适用于会议演讲、视频直播等长时间不间断识别的场景。
使用须知
如需使用Android或iOS SDK,请参见移动端接口说明。
支持的输入格式:PCM(无压缩的PCM或WAV文件)、16 bit采样位数、单声道(mono)。
支持的音频采样率:8000 Hz、16000 Hz。
支持设置返回结果:是否返回中间识别结果,在后处理中添加标点,将中文数字转为阿拉伯数字输出。
支持设置多语言识别:在控制台编辑项目中进行模型选择,详情请参见管理项目。
目前支持的语种和方言模型如下:
-
就近地域智能接入
实时语音识别支持就近地域智能接入,域名为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参数。
1. 鉴权
客户端与服务端建立WebSocket连接时,使用Token进行鉴权。关于Token获取请参见获取Token概述。
2. 开始识别
客户端发起请求,服务端确认请求有效。其中在请求消息中需要进行参数设置,各参数由SDK中SpeechTranscriber对象的set方法设置,各参数含义如下:
参数 |
类型 |
是否必选 |
说明 |
appkey |
String |
是 |
管控台创建的项目Appkey。获取Appkey请前往控制台。 |
format |
String |
否 |
音频编码格式,默认是PCM(无压缩的PCM文件或WAV文件),16bit采样位数的单声道。 |
sample_rate |
Integer |
否 |
音频采样率,默认是16000 Hz,根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。 |
enable_intermediate_result |
Boolean |
否 |
是否返回中间识别结果,默认是false。 |
enable_punctuation_prediction |
Boolean |
否 |
是否在后处理中添加标点,默认是false。 |
enable_inverse_text_normalization |
Boolean |
否 |
是否在后处理中执行ITN,设置为true时,中文数字将转为阿拉伯数字输出,默认是false。
说明
不对词信息进行ITN转换。 |
customization_id |
String |
否 |
自学习模型ID。 |
vocabulary_id |
String |
否 |
定制泛热词ID。 |
max_sentence_silence |
Integer |
否 |
语音断句检测阈值,静音时长超过该阈值会被认为断句,参数范围200ms~6000ms,默认值800ms。 |
enable_words |
Boolean |
否 |
是否开启返回词信息,默认是false。 |
enable_ignore_sentence_timeout |
Boolean |
否 |
是否忽略实时识别中的单句识别超时,默认是false。 |
disfluency |
Boolean |
否 |
过滤语气词,即声音顺滑,默认值false(关闭),开启时需要设置version为4.0。 |
speech_noise_threshold |
Float |
否 |
噪音参数阈值,参数范围:[-1,1]。取值说明如下:
说明
该参数属高级参数,调整需慎重并重点测试。 |
enable_semantic_sentence_detection |
Boolean |
否 |
是否开启语义断句,可选,默认是False。语义断句参数需要和开启中间结果配合使用,即开启该语义断句参数需将中间结果参数同时打开:enable_intermediate_result=true。 |
3. 接收识别结果
客户端循环发送语音数据,持续接收识别结果:
SentenceBegin事件表示服务端检测到了一句话的开始。实时语音识别服务的智能断句功能会判断出一句话的开始与结束,举例如下:
{ "header": { "namespace": "SpeechTranscriber", "name": "SentenceBegin", "status": 20000000, "message_id": "a426f3d4618447519c9d85d1a0d1****", "task_id": "5ec521b5aa104e3abccf3d361822****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "index": 1, "time": 0 } }
header对象参数说明:
参数
类型
说明
namespace
String
消息所属的命名空间。
name
String
消息名称,SentenceBegin表示一个句子的开始。
status
Integer
状态码,表示请求是否成功,见服务状态码。
status_text
String
状态消息。
task_id
String
任务全局唯一ID,请记录该值,便于排查问题。
message_id
String
本次消息的ID。
payload对象参数说明:
参数
类型
说明
index
Integer
句子编号,从1开始递增。
time
Integer
当前已处理的音频时长,单位是毫秒。
TranscriptionResultChanged事件表示识别结果发生了变化。仅当enable_intermediate_result取值为true时会多次返回此消息,即一句话的中间识别结果,举例如下:
{ "header": { "namespace": "SpeechTranscriber", "name": "TranscriptionResultChanged", "status": 20000000, "message_id": "dc21193fada84380a3b6137875ab****", "task_id": "5ec521b5aa104e3abccf3d361822****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "index": 1, "time": 1835, "result": "北京的天", "confidence": 1.0, "words": [{ "text": "北京", "startTime": 630, "endTime": 930 }, { "text": "的", "startTime": 930, "endTime": 1110 }, { "text": "天", "startTime": 1110, "endTime": 1140 }] } }
header对象参数同上述表格说明,name为TranscriptionResultChanged:表示句子的中间识别结果。
payload对象参数说明:
参数
类型
说明
index
Integer
句子编号,从1开始递增。
time
Integer
当前已处理的音频时长,单位是毫秒。
result
String
当前句子的识别结果。
words
List< Word >
当前句子的词信息,需要将enable_words设置为true。
confidence
Double
当前句子识别结果的置信度,取值范围:[0.0,1.0]。值越大表示置信度越高。
SentenceEnd事件表示服务端检测到了一句话的结束,并附带返回该句话的识别结果,举例如下:
{ "header": { "namespace": "SpeechTranscriber", "name": "SentenceEnd", "status": 20000000, "message_id": "c3a9ae4b231649d5ae05d4af36fd****", "task_id": "5ec521b5aa104e3abccf3d361822****", "status_text": "Gateway:SUCCESS:Success." }, "payload": { "index": 1, "time": 1820, "begin_time": 0, "result": "北京的天气。", "confidence": 1.0, "words": [{ "text": "北京", "startTime": 630, "endTime": 930 }, { "text": "的", "startTime": 930, "endTime": 1110 }, { "text": "天气", "startTime": 1110, "endTime": 1380 }] } }
header对象参数同上述表格说明,name为SentenceEnd表示识别到句子的结束。
payload对象参数说明:
参数
类型
说明
index
Integer
句子编号,从1开始递增。
time
Integer
当前已处理的音频时长,单位是毫秒。
begin_time
Integer
当前句子对应的SentenceBegin事件的时间,单位是毫秒。
result
String
当前的识别结果。
words
List< Word >
当前句子的词信息,需要将enable_words设置为true。
confidence
Double
当前句子识别结果的置信度,取值范围:[0.0,1.0]。值越大表示置信度越高。
Words对象参数说明:
参数
类型
说明
text
String
文本。
startTime
Integer
词开始时间,单位为毫秒。
endTime
Integer
词结束时间,单位为毫秒。
4. 结束识别
通知服务端语音数据发送完成,服务端识别结束后通知客户端识别完毕。
服务状态码
在服务的每一次响应中,都包含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! |
并发请求过多。 |
如果是试用版调用,建议您升级为商用版本以增大并发。 如果已是商用版,可购买并发资源包,或通过钉钉搜索群号23050005920,加入智能语音交互产品咨询群,联系阿里云商务扩充您的并发额度。 |
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_CLINET_DATA_TIMEOUT:Client data does not send continuously! |
获取客户端发送的数据超时失败。 |
客户端在调用实时语音识别时请保持实时速率发送,发送完成后及时关闭链接。 |
50000000 |
GRPC_ERROR:Grpc error! |
受机器负载、网络等因素导致的异常,通常为偶发出现。 |
一般重试调用即可恢复,如有大规模报错,请加入钉钉群23050005920咨询产品技术支持。 |
50000001 |
GRPC_ERROR:Grpc error! |
受机器负载、网络等因素导致的异常,通常为偶发出现。 |
一般重试调用即可恢复,如有大规模报错,请加入钉钉群23050005920咨询产品技术支持。 |
52010001 |
GRPC_ERROR:Grpc error! |
受机器负载、网络等因素导致的异常,通常为偶发出现。 |
一般重试调用即可恢复,如有大规模报错,请加入钉钉群23050005920咨询产品技术支持。 |
实时语音识别错误码
状态码 |
状态消息 |
原因 |
解决方案 |
40000004 |
Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time |
请求建立链接后,长时间没有发送任何数据,超过10s后,服务端会返回此错误信息。 |
请在建立链接后和服务端保持交互,比如持续发送语音流,您可以在采集音频的同时进行发送, 发送结束后及时关闭链接。 |
40010004 |
Gateway:CLIENT_DISCONNECT:Client disconnected before task finished! |
在请求处理完成前客户端主动结束。 |
无,或者请在服务端响应完成后再关闭链接。 |
40270003 |
DECODE_ERROR |
音频解码失败。 |
请根据实际音频格式,设置对应的format参数。 |
41000002 |
APPKEY_KEY_IS_NULL |
没有正确设置appkey。 |
请参考官网文档及示例代码。 |