实时语音识别接口说明 - 智能语音交互

计费和并发限制

实时语音识别提供试用版和商用版，费用说明请参见计费项。

使用须知

调用接口前，确认音频格式、采样率和项目模型符合以下要求。

支持的输入格式：单声道（mono）、16 bit 采样位数，包括 PCM、PCM 编码的 WAV、OGG 封装的 OPUS。
支持的音频采样率：8000 Hz、16000 Hz。
支持设置返回结果：是否返回中间识别结果，在后处理中添加标点，将中文数字转为阿拉伯数字输出。
不支持说话人分离，无法进行角色分析。
识别使用的语种和方言由项目模型决定，不能通过请求参数指定。模型配置方法，请参见管理项目。

服务地址

访问类型	说明	URL
外网访问	使用新加坡地域的服务地址。	wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1

交互流程

说明

服务端响应的 header.task_id 标识本次识别任务。记录该值，便于排查问题。

1. 鉴权

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

获取方法，请参见通过 SDK 获取 Token。

2. 开始识别

客户端发送 StartTranscription 指令，并设置识别参数。服务端返回 TranscriptionStarted 后，客户端开始发送音频。使用 SDK 时，通过对应的参数设置方法完成配置。参数含义如下：

参数	类型	是否必选	说明
appkey	String	是	在智能语音交互控制台创建的项目 Appkey。
format	String	否	音频格式：pcm、wav、opus。
sample_rate	Integer	否	音频采样率，默认是16000 Hz，根据音频采样率在控制台对应项目中配置支持该采样率及场景的模型。
enable_intermediate_result	Boolean	否	是否返回中间识别结果，默认是false。
enable_punctuation_prediction	Boolean	否	是否在后处理中添加标点，默认是false。
enable_inverse_text_normalization	Boolean	否	是否开启逆文本正则化（ITN），将中文数字转为阿拉伯数字输出。默认值为 false。
customization_id	String	否	自学习模型ID。
vocabulary_id	String	否	定制泛热词ID。
max_sentence_silence	Integer	否	静音断句阈值，单位为毫秒。检测到语音后的静音时长超过阈值时触发断句。取值范围：200～2000，默认值：800。开启 enable_semantic_sentence_detection 后，不使用此阈值进行静音断句，但参数值仍需在允许范围内。静音时长按音频数据计算，不是停止发送数据后的等待时长。需要通过静音断句时，应持续发送包含静音段的音频；PCM 音频的静音段可以用零值采样表示。
enable_words	Boolean	否	是否开启返回词信息，默认是false。
disfluency	Boolean	否	过滤语气词，即声音顺滑，默认值false（关闭）。
speech_noise_threshold	Float	否	噪音参数阈值，参数范围：[-1,1]。取值说明如下：取值越趋于-1，噪音被判定为语音的概率越大。取值越趋于+1，语音被判定为噪音的概率越大。重要该参数属高级参数，调整需慎重并重点测试。
enable_semantic_sentence_detection	Boolean	否	是否开启语义断句，可选，默认是False。语义断句参数需要和开启中间结果配合使用，即开启该语义断句参数需将中间结果参数同时打开：enable_intermediate_result=true。

3. 接收识别结果

客户端持续发送音频数据并接收识别事件。以下 JSON 示例使用中文语音，展示各事件的消息结构。

header对象参数说明：

参数	类型	说明
namespace	String	消息所属的命名空间。
name	String	事件名称。
status	Integer	状态码，表示请求是否成功，见服务状态码。
status_text	String	状态消息。
task_id	String	任务全局唯一ID，请记录该值，便于排查问题。
message_id	String	本次消息的ID。

SentenceBegin

SentenceBegin事件表示服务端检测到了一句话的开始。实时语音识别服务的智能断句功能会判断出一句话的开始与结束，举例如下：

{
        "header": {
                "namespace": "SpeechTranscriber",
                "name": "SentenceBegin",
                "status": 20000000,
                "message_id": "a426f3d4618447519c9d85d1a0d1****",
                "task_id": "5ec521b5aa104e3abccf3d361822****",
                "status_text": "Gateway:SUCCESS:Success."
        },
        "payload": {
                "index": 1,
                "time": 0
        }
}

payload对象参数说明：

参数	类型	说明
index	Integer	句子编号，从1开始递增。
time	Integer	当前已处理的音频时长，单位为毫秒。

TranscriptionResultChanged

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

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. 结束识别

音频发送完成后，发送 StopTranscription 指令结束本次识别任务。服务端处理剩余音频，并在任务结束时返回 TranscriptionCompleted。收到该事件后再关闭连接。

StopTranscription 不是保持任务运行的强制断句指令。如果剩余音频中有有效语音，服务端可能先返回 SentenceEnd；仅包含静音的任务不一定返回 SentenceEnd。

服务状态码

通过响应中的 header.status 和 header.status_text 判断请求状态。下表列出常见错误及处理方法。

通用错误码

状态码	状态消息	原因	解决方案
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语音文件，且设置`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	不支持的接口或参数。	请检查调用时传递的参数内容是否和官网文档要求的一致，并结合错误信息对比排查，设置为正确的参数。比如是否通过curl命令执行RESTful接口请求，拼接的URL是否合法。
40010003	Gateway:DIRECTIVE_INVALID:[xxx]	客户端侧通用错误码。	表示客户端传递了不正确的参数或指令，在不同的接口上有对应的详细报错信息，请参考对应文档进行正确设置。
40010004	Gateway:CLIENT_DISCONNECT:Client disconnected before task finished!	在请求处理完成前客户端主动结束。	收到 TranscriptionCompleted 后再关闭连接。
40010005	Gateway:TASK_STATE_ERROR:Got stop directive while task is stopping!	客户端发送了当前不支持的消息指令。	检查指令发送顺序。任务正在结束时，不要重复发送 StopTranscription。
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!	获取客户端发送的数据超时失败。	按实时速率持续发送音频。发送完成后发送 StopTranscription，收到 TranscriptionCompleted 后再关闭连接。
50000000	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。
50000001	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。
52010001	GRPC_ERROR:Grpc error!	受机器负载、网络等因素导致的异常，通常为偶发出现。	一般重试调用即可恢复。

实时语音识别错误码

状态码	状态消息	原因	解决方案
40000004	Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time	请求建立连接后，长时间没有发送任何数据，超过10s后，服务端会返回此错误信息。	建立连接后持续发送音频，可边采集边发送。音频发送完成后发送 StopTranscription，收到 TranscriptionCompleted 后再关闭连接。
40270002	NO_VALID_AUDIO_ERROR	无效的音频。	从音频中没有识别出有效文本。
40270003	DECODE_ERROR	音频解码失败。	请根据实际音频格式，设置对应的format参数。
41000002	APPKEY_KEY_IS_NULL	没有正确设置appkey。	请参考官网文档及示例代码。