websocket接口
功能介绍
一句话识别websocket接口支持识别1min以内的音频，交互过程如图 客户端和服务端交互流程所示，主要分为开始识别、发送音频数据，结束识别、断开连接四个步骤。
websocket接口同http接口一致按次计费，只要建立连接成功，发送音频，服务开始识别，则本次调用计费生效。如果用户发送错误end请求或者持续20s未发送音频而产生了报错，该次调用依然认为生效。如果连接成功后未发送音频直接断开，或者请求字段不正确而产生异常，则认为本次调用无效，不会纳入计费次数。
wss-URI
- wss-URI格式
- 参数说明
表1 参数说明 参数名
是否必选
说明
project_id
是
项目编号。获取方法，请参见获取项目ID。
表2 请求Header参数 参数
是否必选
参数类型
描述
X-Auth-Token
是
String
用户Token。
用于获取操作API的权限。获取方法请参见认证鉴权。响应消息头中X-Subject-Token的值即为Token。
Enterprise-Project-Id
否
String
企业项目ID。SIS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。
获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。
企业项目创建步骤请参见用户指南。
说明：账户创建企业项目后，在传参时，有以下三类场景。
- 携带正确的ID，正常使用SIS服务，账单归到企业ID对应的企业项目中。
- 携带错误的ID，正常使用SIS服务，账单的企业项目会被分类为“default”。
- 不携带ID，正常使用SIS服务，账单的企业项目会被分类为“default”。
开始识别
- 功能介绍
当wss握手请求收到成功响应后，客户端到服务端的通信协议会升级为Websocket协议。通过Websocket协议，客户端发送开始识别请求，用于配置一句话识别的配置信息。
- 请求消息
表3 参数说明 参数名
是否必选
参数类型
说明
command
是
String
表示客户端发送开始识别请求，参数值需设置为START。
config
是
Object
配置信息。结构信息请参见表 config数据结构。
表4 config数据结构 参数
是否必选
参数类型
说明
audio_format
是
String
支持语音的格式，请参见表 audio_format取值范围。
property
是
String
所使用的模型特征串。通常是 “语种_采样率_领域”的形式，例如chinese_8k_common。请参见表 property取值范围。
add_punc
否
String
表示是否在识别结果中添加标点，取值为yes 、 no，默认no。
digit_norm
否
String
表示是否将语音中的数字识别为阿拉伯数字，取值为yes 、 no，默认为yes。识别结束后，会将数字识别为阿拉伯数字。
interim_results
否
String
是否输出中间结果，可以为yes或no。默认为no，表示不输出中间结果。
vocabulary_id
否
String
热词表id，不使用热词则不填写。
创建热词表信息请参考创建热词表。
need_word_info
否
String
表示是否在识别结果中输出分词结果信息，取值为“yes”和“no”，默认为“no”。
表5 property取值范围 property取值
说明
chinese_8k_general
支持采样率为8k的中文普通话语音识别，采用新一代端到端识别算法，识别准确率更高。
格式支持pcm8k16bit/alaw8k8bit/ulaw8k8bit，区域支持cn-east-3和cn-north-4（强烈推荐使用）。
chinese_16k_general
支持采样率为16k的中文普通话语音识别，采用新一代端到端识别算法，识别准确率更高。
格式支持pcm16k16bit/alaw16k8bit/ulaw16k8bit，区域支持cn-east-3和cn-north-4（强烈推荐使用）。
chinese_8k_common
支持采样率为8k的中文普通话语音识别。
chinese_16k_common
支持采样率为16k的中文普通话语音识别。
sichuan_16k_common
支持采样率为16k的中文普通话与四川话方言语音识别。区域仅支持cn-north-4。
cantonese_16k_common
支持采样率为16k的粤语方言语音识别。区域仅支持cn-north-4。
shanghai_16k_common
支持采样率为16k的上海话方言语音识别。区域仅支持cn-north-4。
表6 audio_format取值范围 audio_format取值
说明
pcm16k16bit
16k16bit单通道录音数据。
pcm8k16bit
8k16bit单通道录音数据。
ulaw16k8bit
16k8bit ulaw单通道录音数据。
ulaw8k8bit
8k8bit ulaw单通道录音数据。
alaw16k8bit
16k8bit alaw单通道录音数据。
alaw8k8bit
8k8bit alaw单通道录音数据。
目前仅支持裸音频格式，仅支持pcm编码的wav格式，不支其他wav头或者arm格式的编码。
- 示例
{ "command": "START", "config": { "audio_format": "pcm8k16bit", "property": "chinese_8k_common", "add_punc": "yes", "interim_results": "yes", "need_word_info": "yes" } } - 状态码
状态码请参见状态码。
- 错误码
错误码请参见错误码。
发送音频数据
在收到“开始识别”的响应之后，可以开始发送音频数据。为节省流量，音频以二进制数据帧形式（binary message）的方式发送。
音频数据将分片发送，也即在获得一定量音频数据的同时就可以发送一个binary message，每个分片建议在50ms~1000ms之间，建议在需要实时反馈的情况下100ms，不需要实时反馈的情况下500ms。
结束识别
- 功能介绍
对于识别中的对话，需要在Websocket上发送“结束识别”的请求来取消或结束识别。 "结束识别"请求使用文本类型的数据帧(text message)发送，命令和参数以json字符串的形式提供。
- 请求消息
表7 参数说明 参数名
是否必选
参数类型
说明
command
是
String
表示客户端结束识别请求，参数值设置为END。
- 示例
{ "command": "END" } - 状态码
状态码请参见状态码。
- 错误码
错误码请参见错误码。
响应结果
- 开始识别响应
由于WebSocket是全双工的，因此响应就是从服务器端发送给客户端的消息，但也并不是所有的请求信息都有一条对应的响应。服务器端收到“开始识别”请求时，会给出如下响应消息，以json字符串形式放置在text message中。
表8 响应参数 参数名
参数类型
说明
resp_type
String
响应类型。参数值为START，表示开始识别响应。
trace_id
String
服务内部的令牌，可用于在日志中追溯具体流程。
示例
{ "resp_type": "START", "trace_id": "567e8537-a89c-13c3-a882-826321939651" } - 事件响应
服务器端检测到某些事件时，会给出如下响应消息，以json字符串形式放置在text message中。
表9 响应参数 参数名
参数类型
说明
resp_type
String
响应类型。参数值为EVENT，表示开始识别响应。
trace_id
String
服务内部的令牌，可用于在日志中追溯具体流程。
event
String
具体的事件，一句话识别中仅会出现"EXCEEDED_AUDIO”，当输入音频超过1min时，会返回该事件。
timestamp
Integer
保留字段。将来会用于此事件发生的具体时间，以会话开始作为0点，单位为ms。
示例
{ "resp_type": "EVENT", "trace_id": "567e8537-a89c-13c3-a882-826321939651", "event": "EXCEEDED_AUDIO", "timestamp": 1500 } - 结果响应
服务端在收到客户端发送的连续音频数据后， 当服务端识别出结果后会实时向客户端按句推送识别结果响应消息， 以json字符串形式放置在text message中。
表10 响应参数 参数名
参数类型
说明
resp_type
String
响应类型。参数值为RESULT，表示识别结果响应。
trace_id
String
服务内部的令牌，可用于在日志中追溯具体流程。
segments
Array of objects
多句结果。
请参考表 segment 数据结构。
表11 segment 数据结构 参数名
参数类型
说明
start_time
Integer
一句的起始时间戳，单位为ms。
end_time
Integer
一句的结束时间戳，单位为ms。
is_final
Boolen
true表示是最终结果， false表示为中间临时结果。
result
Object
调用成功表示识别结果，调用失败时无此字段。
请参考表 result数据结构。
表12 result数据结构 参数名
参数类型
说明
text
String
识别结果。
score
Float
识别结果的置信度，取值范围：0~1。此值仅会在最终结果时被赋值，在中间结果时统一置为“0.0”。
说明：目前置信度作用不是太大，请勿过多依赖此值。
word_info
Array of Object
分词输出列表。
表13 word_info 数据结构 参数名
是否必选
参数类型
说明
start_time
否
Integer
起始时间
end_time
否
Integer
结束时间
word
否
String
分词
示例
{ "resp_type": "RESULT", "trace_id": "567e8537-a89c-13c3-a882-826321939651", "segments": [ { "start_time": 100, "end_time": 1500, "is_final": false, "result": { "text": "第一句中间结果", "word_info": [ { "start_time": 100, "end_time": 800, "word": "第一" }, { "start_time": 800, "end_time": 1000, "word": "句" }, { "start_time": 1000, "end_time": 1500, "word": "结果" } ], "score": 0.0 }, }, ] } - 错误响应
- 配置串错误，包括存在不识别的配置串，或者配置串值的范围不合法。
- 时序不正确，比如连续发送两次“开始识别”指令。
- 识别过程中发生错误，比如音频解码发生错误。
表14 响应参数 参数名
参数类型
说明
resp_type
String
参数值为ERROR，表示错误响应。
trace_id
String
服务内部的跟踪令牌，可用于在日志中追溯具体流程。
在某些错误情况下，可能没有此字段。
error_code
String
错误码列表。详细错误码解释，请参见错误码。
error_msg
String
返回错误信息。
示例
{ "resp_type": "ERROR", "trace_id": "567e8537-a89c-13c3-a882-826321939651", "error_code": "SIS.0002", "error_msg": "***" } - 结束识别响应
服务器端收到“结束识别”请求时或语音识别过程中发生错误，服务端会向客户端推送如下响应消息，以json字符串形式放置在text message中。
表15 响应参数 参数名
参数类型
说明
resp_type
String
参数值为END，表示结束识别响应。
trace_id
String
服务内部的令牌，可用于在日志中追溯具体流程。
reason
String
结束原因，详情请参见表 结束原因表。
示例
{ "resp_type": "END", "trace_id": "567e8537-a89c-13c3-a882-826321939651", "reason": "NORMAL", }
代码示例
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.WebSocket;
import okhttp3.WebSocketListener;
import okio.ByteString;
/**
* 此demo仅供测试使用，强烈建议使用SDK
* 使用前需已配置okhttp、okio jar包。jar包可通过下载SDK获取。
*/
public class SasrWebsocketDemo {
public void sasrWebsocketDemo() {
try {
// endpoint和projectId需要替换成实际信息。
String url = "wss://{{endpoint}}/v1/{{project_id}}/asr/short-audio";
String token = "对应region的token";
byte[] data = null; // 存放将要发送音频的byte数组
OkHttpClient okHttpClient = new OkHttpClient();
Request request = new Request.Builder().url(url).header("X-Auth-Token", token).build();
WebSocket webSocket = okHttpClient.newWebSocket(request, new MyListener());
webSocket.send("{\"command\": \"START\", \"config\": {\"audio_format\": \"pcm8k16bit\", \"property\": \"chinese_8k_common\"}}");
webSocket.send(ByteString.of(data)); // audio太大注意要分片发送，否则会报错。建议分片大小3200
webSocket.send("{ \"command\": \"END\"}");
Thread.sleep(10000);
webSocket.close(1000, null);
} catch (Exception e) {
e.printStackTrace();
}
}
class MyListener extends WebSocketListener {
@Override
public void onOpen(WebSocket webSocket, Response response) {
System.out.println("conneected");
}
@Override
public void onClosed(WebSocket webSocket, int code, String reason) {
System.out.println("closed");
}
@Override
public void onFailure(WebSocket webSocket, Throwable t, Response response) {
t.printStackTrace();
}
@Override
public void onMessage(WebSocket webSocket, String text) {
System.out.println(text);
}
}
public static void main(String[] args) {
SasrWebsocketDemo sasrWebsocketDemo = new SasrWebsocketDemo();
sasrWebsocketDemo.sasrWebsocketDemo();
}
}
