语音转写实时推送集成文档

一、对要回调的会议室注册回调

POST /api/rest/external/v1/callbacks/meetingRoom/event?enterpriseId=XXX&signature=XXX
{
  "confNumber": "9132966806",
  "callbackEvent": "AIRealTimeTranscription",
  "handlerUrl": "ws://172.34.111.222:3333/recv/asr/result/v1",
  "version": "v2"
}

二、handlerUrl实现说明

2.1 接口清单

接口类型	接口功能	路径	备注
WebSocket	推送实时语音转写结果	用户自定义	实时语音转写结果推送

2.2 约定

- 考虑低延迟和后期消息扩展，使用websocket协议进行实时语音转写结果推送

- 时间格式：unix时间戳，单位毫秒。如：1748949792000

- 字符编码：UTF-8

2.3 接口描述

- 请求URL ws(s)://ip:port/selfDefinePath?appid=xx&ts=yy&signature=zz

2.4 接口主要流程

- 握手阶段 - 开始会话 - 转写推送 - 会话结束

2.4.1 握手阶段

握手阶段，客户端需要对请求进行签名，服务端会对签名进行合法性校验。签名校验参数在url中携带，签名校验通过才可以进行后续操作。(签名校验是接收转写结果的ws服务端进行，如果是纯内网，用户可自行决定是否校验)

- 请求参数

参数	类型	必须	说明	示例
appid	string	是	应用ID，标记请求从哪里来	xylink
ts	string	是	当前unix时间戳，单位毫秒; 如果客户端与服务器unix时间相差过大(10分钟以上)，建议报错，防重放	1748949792000
signature	string	是	接口签名， urlencode(base64(HMAC_SHA256(utc+appid, key))) 签名需要的密钥见获取密钥签名计算可以使用 jar包，见回调鉴权	见`签名规则`

- 签名规则

假设url为`ws://172.34.111.222:3333/recv/asr/result/v1?appid=xylink&ts=1748949792000`

1、将必填的appid与ts字段解析出来进行拼接，得到字符串`xylink1748949792000`

2、将字符串`xylink1748949792000`进行HMAC_SHA256加密后base64，假设秘钥为`testKey`，得到的加密后base64结果为`CV+stYTEdV6KsOkmQGNmAgs+CNinAxmDAR4jnQlJKsY=`

3、将base64之后的内容先做urlencode消除特殊字符，再将urlencode后的内容作为新的参数追加到url中，得到
`ws://172.34.111.222:3333/recv/asr/result/v1?appid=xylink&ts=1748949792000&signature=CV%2BstYTEdV6KsOkmQGNmAgs%2BCNinAxmDAR4jnQlJKsY%3D`

- 请求示例

ws://172.34.111.222:3333/recv/asr/result/v1?appid=xylink&ts=1748949792000&signature=CV%2BstYTEdV6KsOkmQGNmAgs%2BCNinAxmDAR4jnQlJKsY%3D

- ws网络连接成功后，服务器需要对签名进行校验，根据情况返回对应的状态码 - 响应示例

//成功
{
    "action": "auth_ack",
    "desc": "success",               #成功必须回"success"，以便发送后续转写消息
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话,后续推送消息都会带上这个ID
}

//失败
{
    "action": "auth_ack",
    "desc": "invalid parameter",     #失败的错误描述，用户可以自定义
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话
}

- 响应状态码说明

描述desc	说明	解决方式
success	成功	可以继续后续操作
invalid parameter	缺少必填参数	检查appid、ts、signature等参数是否按要求填写
clock offset verification failed	时钟偏移校验失败	确保客户端时间与服务器同步
signature verification failed	签名校验不匹配	检查签名生成逻辑，检查签名key是否正确

2.4.2 开始会话

- 握手连接签名校验成功后，客户端会推送转写结果

- 请求参数

参数	类型	必须	默认值	说明	示例
action	string	是	/	begine ：开始推送	begine
sid	string	是	/	当次ws会话的唯一id	ch312c0e3f63609f0900
enterpriseId	string	是	default_enterprise	会议室号所属的企业id，一般私有云都是固定default_enterprise	default_enterprise
confNo	string	是	/	会议室号，标记是哪个会议室的转写结果，confNo在不同的呼叫是不变的。	90012345
meetingId	string	是	/	会议室ID，标记是哪次组会的转写结果，同一个confNo的不同呼叫，meetingId不一样。	189-bj1-privateSig1-1177415426335

- 请求示例

{
    "sid": "ch312c0e3f63609f0900",
    "action": "begine",
    "data":{
        "enterpriseId":"default_enterprise",
        "confNo": "90012345",
        "meetingId": "189-bj1-privateSig1-1177415426335"
     } 
}

2.4.3 实时转写结果推送

- 在实时转写过程中，客户端不断推送实时语音转写结果

参数	类型	说明
sid	string	会话id，一个ws链接一个唯一ID
action	string	push_result ：推送转写结果
data	string	转写结果

- 转写结果示例

//成功
{
    "sid": "ch312c0e3f63609f0900"
    "action": "push_result",
    "data": {
        "callNumber": "+86-10506",
        "dn": "测试员",
        "callUri": "240438186@DESK",
        "pid": 65664
        "seId": "jy2i2kb623ikj12o37fb90afhbst0kym",
        "srcLang": "zh",
        "src": "好的领导",
        "targetLang": "en",
        "target": "Good leadership.",
        "startTime": 1772447728343,
        "endTime": 1772447730743,
        "seqNo": 1,
        "isActive": true,
        "isEnd": false
    }
}

字段	含义
callNumber	发言端的注册号
dn	发言端名称
callUri	发言端身份，用不上可忽略
pid	发言端媒体身份id，用不上可忽略
seId	句子ID，当isEnd为true后，在下一句更新seId；isEnd为false时不变
srcLang	源语言，"zh":中文; "en":英文
src	源语言转写结果
targetLang	翻译语言，"en":英文; "zh":中文
target	翻译结果
startTime	句子开始时间，单位ms
endTime	句子结束时间，单位ms
seqNo	句子序号, 当isEnd为true后，序号才会+1
isActive	发言者是否为语音激励端，用不上可忽略
isEnd	true: 完整句子; false:临时的不完整句子。注意seqNo与seId都会收到isEnd字段变化的影响

2.4.5 会话结束

- 会议结束后停止推送转写结果，ws会话正常结束

- 请求示例

{
    "sid": "ch312c0e3f63609f0900",
    "action": "end",
    "data":{
        "confNo": "90012345",
        "meetingId": "189-bj1-privateSig1-1177415426335",
        "enterpriseId":"default_enterprise"
     } 
}

2.5 流程总结

2026-03-11 19:13:38

导出PDF文档