接口说明

对长时间的语音数据流进行识别,适用于会议演讲、视频直播等长时间不间断识别的场景。

使用须知

注意

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

  • 支持的输入格式:PCM(无压缩的PCM或WAV文件)、16bit采样位数、单声道(mono)。

  • 支持的音频采样率:8000Hz/16000Hz。

  • 支持设置返回结果:是否返回中间识别结果,在后处理中添加标点,将中文数字转为阿拉伯数字输出。

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

服务地址

访问类型

说明

URL

外网访问

所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL)。

wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1

上海ECS内网访问

使用阿里云上海ECS(即ECS地域为华东2(上海)),可使用内网访问URL。ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。

说明

  • 使用内网访问方式,将不产生ECS实例的公网流量费用。

  • 关于ECS的网络类型请参见网络类型

ws://nls-gateway.cn-shanghai-internal.aliyuncs.com:80/ws/v1

交互流程

交互流程
说明

所有服务端的响应都会在返回信息的header包含用于表示本次识别任务的task_id参数,请记录下该值,如果发生错误,请将task_id和错误信息提交到工单。

1. 鉴权

客户端与服务端建立WebSocket连接时,使用Token进行鉴权。关于Token获取请参见获取Token

2. 开始识别

客户端发起请求,服务端确认请求有效。其中在请求消息中需要进行参数设置,各参数由SDK中SpeechTranscriber对象的set方法设置,各参数含义如下:

参数

类型

是否必选

说明

appkey

String

管控台创建的项目appkey。

format

String

音频编码格式,默认是PCM(无压缩的PCM文件或WAV文件),16bit采样位数的单声道。

sample_rate

Integer

音频采样率,默认是16000Hz,根据音频采样率在管控台对应项目中配置支持该采样率及场景的模型。

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~2000ms,默认值800ms。

enable_words

Boolean

是否开启返回词信息,默认是False。

enable_ignore_sentence_timeout

Boolean

是否忽略实时识别中的单句识别超时,默认是False。

disfluency

Boolean

是否对识别文本进行顺滑(去除语气词,重复说等),默认是False。

speech_noise_threshold

Float

噪音参数阈值,参数范围:[-1,1]。取值说明如下:

  • 取值越趋于-1,噪音被判定为语音的概率越大。

  • 取值越趋于+1,语音被判定为噪音的概率越大。

说明

该参数属高级参数,调整需慎重并重点测试。

enable_semantic_sentence_detection

Boolean

是否开启语语义断句,可选,默认是False。

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]。值越大表示置信度越高。

    Word对象参数说明:

    参数

    类型

    说明

    text

    String

    文本。

    startTime

    Integer

    词开始时间,单位为毫秒。

    endTime

    Integer

    词结束时间,单位为毫秒。

4. 结束识别

通知服务端语音数据发送完成,服务端识别结束后通知客户端识别完毕。

服务状态码

在服务的每一次响应中,都包含status字段,即服务状态码,此处列举通用错误码、网关错误码、配置错误码表格,如下表所示。

  • 通用错误码:

    错误码

    原因

    解决办法

    40000001

    身份认证失败

    检查使用的令牌是否正确,是否过期。

    40000002

    无效的消息

    检查发送的消息是否符合要求。

    40000010

    免费试用已到期

    请前往控制台开通商用服务。

    403

    令牌过期或无效的参数

    首先检查使用的令牌是否过期,然后检查参数值设置是否合理。

    40000004

    空闲超时

    确认是否长时间(10秒)没有发送数据到服务端。

    40000005

    请求数量过多

    检查是否超过了并发连接数或者每秒钟请求数。如果超过并发数,建议从免费版升级到商用版,或者商用版扩容并发资源。

    40000000

    默认的客户端错误码

    查看错误消息或提交工单。

    41010120

    客户端超时错误

    客户端连续10秒及以上没有发送数据,导致客户端超时错误。

    50000000

    默认的服务端错误

    如果偶现可以忽略,重复出现请提交工单。

    50000001

    内部调用错误

    如果偶现可以忽略,重复出现请提交工单。

    52010001

    内部调用错误

    如果偶现可以忽略,重复出现请提交工单。

  • 网关错误:

    错误码

    原因

    解决办法

    40010001

    不支持的接口

    使用了不支持的接口,如果使用SDK请提交工单。

    40010002

    不支持的指令

    使用了不支持的指令,如果使用SDK请提交工单。

    40010003

    无效的指令

    指令格式错误,如果使用SDK请提交工单。

    40010004

    客户端提前断开连接

    检查是否在请求正常完成之前关闭了连接。

    40010005

    任务状态错误

    发送了当前任务状态不能处理的指令。

  • 配置错误:

    错误码

    原因

    解决办法

    40020105

    应用不存在

    解析路由时找不到应用。

    40020106

    appkey和token不匹配

    检查应用apkey是否正确,是否与令牌归属同一个账号。

    40020503

    子账户鉴权失败

    使用父账户对调用的子账户授权POP API的访问权限。

  • 实时语音识别:

    错误码

    原因

    解决办法

    41040201

    客户端10s内停止发送数据

    检查网络问题,或者检查业务中是否存在不发数据的情况。

    41040202

    客户端发送数据过快,服务器资源已经耗尽

    检测客户端发包是否过快,是否按照1:1的实时率来发包。

    41040203

    客户端发送音频格式不正确

    请将音频数据的格式转换为SDK目前支持的音频格式发包。

    41040204

    客户端调用方法异常

    客户端应该先调用发送请求接口,在发送请求完毕后再调用其他接口。

    41040205

    客户端设置MAXSILENCE_PARAM方法异常

    参数MAXSILENCE_PARAM的取值范围200~2000。

    41050008/41010101

    采样率不匹配

    检查实际语音的采样率(实时识别场景ASR只支持8K 16bit或者16K 16bit,单声道)、代码调用时设置的采样率(8K或者16K)和控制台上Appkey绑定的ASR模型采样率是否一致。

    不支持的采样率

    发起调用时,请注意代码中设置的采样率参数(8000或16000)与管控台上appkey对应的模型(8k或16k)匹配。

    51040101

    服务端内部错误

    未知错误。

    51040103

    实时语音识别服务不可用

    查看实时语音识别服务是否有任务堆积等导致任务提交失败。

    51040104

    请求实时语音识别服务超时

    排查实时语音识别日志。

    51040105

    调用实时语音识别服务失败

    检查实时语音识别服务是否启动,端口是否正常开启。

    51040106

    实时语音识别服务负载均衡失败,未获取到实时语音识别服务的IP地址

    检查VPC中的实时语音识别服务机器是否有异常。

    51070103

    后处理服务参数配置错误

    若使用的模型为非电话—通用行业—英语模型,请通过管控台再次选择模型,刷新服务端参数。若仍无法解决问题,请提交工单。