1. 接口概述

1.1 接口清单

接口序号	接口类型	接口功能	路径	备注
1	HTTP POST	分配转写资源	/api/rest/external/v1/transcription/task/allocate	需签名鉴权，返回用于后续操作的具体地址
2	WebSocket	实时语音转写	/api/rest/aigw/platform/realtime/asr/v1	实时语音转写接口; 可以对外提供服务

1.2 约定

使用websocket协议进行实时语音转写
时间格式：unix时间戳，单位毫秒。如：1748949792000
字符编码：UTF-8
音频格式：单声道、16bit量化、16KHz采样率的PCM音频数据。即每毫秒数据32字节。

1.3 接口描述

请求URL ws(s)://ip:port/api/rest/aigw/platform/realtime/asr/v1?appid=xx&ts=yy&signature=zzz

1.4 接口主要流程

sequenceDiagram
    participant Client
    participant 云平台
    participant AI_Service

    Note over Client,AI_Service: 鉴权资源分配
    Client->>云平台: POST /接口1,分配转写资源
    云平台-->>AI_Service: {分配realtimeAsrTaskUrl}
    云平台-->>Client: {realtimeAsrTaskUrl}

    Note over Client,AI_Service: 实时音频流转写
    Client->>AI_Service: WS /接口2, realtimeAsrTaskUrl
    AI_Service-->>Client: 返回转写结果

TODO: HTTP请求资源分配，德成补充

1.4.1 ws握手阶段

握手阶段，客户端需要对请求进行签名，服务端会对签名进行合法性校验。签名校验参数在url中携带，签名校验通过才可以进行后续操作。

请求参数

参数	类型	必须	说明	示例
appid	string	是	应用ID	xylink
ts	string	是	当前unix时间戳，单位毫秒; 如果客户端与服务器unix时间相差过大(10分钟以上)，会报错，防重放	1748949792000
signature	string	是	接口签名， urlencode(base64(HMAC_SHA256(appid+ts, key)))	见`签名规则`

签名规则

假设url为ws://172.34.111.222:3333/api/rest/aigw/platform/realtime/asr/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/api/rest/aigw/platform/realtime/asr/v1?appid=xylink&ts=1748949792000&signature=CV%2BstYTEdV6KsOkmQGNmAgs%2BCNinAxmDAR4jnQlJKsY%3D

请求示例，其中ts是url生成时的时间戳(单位:ms)，url有效期10分钟(url分配后10分钟内使用，握手成功之后保持ws长连接的时间不限制)

ws://172.34.111.222:3333/api/rest/aigw/platform/realtime/asr/v1?appid=xylink&ts=1773218935817&signature=CV%2BstYTEdV6KsOkmQGNmAgs%2BCNinAxmDAR4jnQlJKsY%3D

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

//成功
{
    "action": "auth_result",
    "code": "0000",
    "desc": "success",               #认证通过
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话
}

//失败
{
    "action": "auth_result",
    "desc": "invalid parameter",     #认证失败，检查url是否在有效期内
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话
}

响应状态码说明

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

1.4.2 ws开始会话

握手连接签名校验成功后，可通过发送文本消息向服务器发起开始转写请求
请求参数

参数	类型	必须	默认值	说明	示例
sid	string	是	/	认证成功返回的sid，标记当前这路ws会话	ch312c0e3f63609f0900
action	string	是	/	begin ：开始转写 end：结束转写	begin
srcLang	string	否	zh	音频流语言类型，有 zh：中文 en：英文两种，暂不支持其他语言。不填默认中文	zh
tarLang	string	否	en	翻译的目标语言类型，开启enableTran后有效。支持zh：中文 en：英文两种，暂不支持其他语言。不填默认是srcLang之外的另一种语言	en
enableTrans	bool	否	false	是否开启中英互译，不填默认不开启	false
enableRole	bool	否	false	是否开启角色分离功能，持续优化中，不填默认不开启	false

请求示例

{
    "sid":"ch312c0e3f63609f0900",
    "action": "begin",
    "srcLang": "zh",
    "tarLang":"en",
    "enableTrans":false,
    "enableRole":false
}

响应示例

//成功
{
    "action": "begin_result",
    "code": "0000",
    "desc": "success",
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话
}

//失败
{
    "action": "begin_result",
    "code": "2001",
    "desc": "unsupported language types",
    "sid": "ch312c0e3f63609f0900"    #服务器生成的唯一ID，标记当前这一路ws会话
}

状态码说明

状态码code	描述desc	说明
0000	success	成功
2001	unsupported language types	不支持的语言类型
2002	ai engine no resources	转写资源不足

1.4.3 ws实时转写

在实时转写过程中，客户端不断构造binary message发送到服务端，内容是音频的二进制数据。音频流每40ms发送1280字节
服务端收到音频数据流，将实时转写内容以text message的方式发送给客户端，包含转写结果
转写结果参数

参数	类型	说明
action	string	result ：转写结果
code	string	状态码
desc	string	状态描述
sid	string	会话id，一个ws链接一个唯一ID
data	object	转写结果（JSON对象）

状态码code

描述desc

说明

解决方式

0000

success

成功

可以继续后续操作

3001

no audio data

连续15秒没有收到音频流

是否没有音频数据发送，如果没音频数据，

但是需要继续维持ws链接，可以发送静音包维持；

如果音频数据发送完毕，应该发送{ "action": "end"}消息明确需要转写结束，

服务器转写完毕后会正常断开ws链接。

转写结果示例

//成功
{
    "action": "ai_result",
    "code": "0000",
    "data": {...},
    "desc": "success",
    "sid": "ch312c0e3f63609f0900"
}

//失败
{
    "action": "ai_result",
    "code": "3001",
    "desc": "no audio data",
    "sid": "ch312c0e3f63609f0900"
}

其中data为转写结果的json消息

{
    "bt": 1358,
    "et": 2038,
    "text": "今天星期一",
    "targetText": "Today is Monday",
    "srcLang": "zh",
    "targetLang": "en",
    "isEnd": true,
    "seId": "5ee460bc1f9742e395e96cdd3bea09a3",
    "seNum": 12,
    "seIndex": 2,
    "totalNum": 20,
    "role": 0
}

字段	含义
bt	句子开始时间，单位ms
et	句子结束时间，单位ms
text	转写结果
targetText	翻译后的结果
srcLang	源语言类型
targetLang	翻译后的语言类型
isEnd	标记句子是否结果，true完整句子；false中间结果
seId	句子ID，当isEnd为true后，会成新的seId；isEnd为false时不变
seNum	返回完整句子的个数，即isEnd=true的个数，从1递增
seIndex	返回当前句子的序号，从1递增，isEnd=true归零,重新从1递增
totalNum	返回总个数，含isEnd=false的中间结果次数
role	分离的角色编号，角色从1开始计算; 若未开启角色分离,是-1;若开启角色分离,但是中间结果未分离出来是0

1.4.4 ws会话结束

音频数据上传完毕后，客户端需要发送一个结束消息，明确告知服务器转写结束，服务器将转写内容传输完毕后，会主动断开ws链接
由于语音转写是异步的，数据上传完毕后，客户端不要主动断开ws链接，必须发送{ "action": "end"}，然后等待服务器主动断开，否则可能会丢失最后一句转写内容。
请求示例

{
  "action":"end"
}

响应示例

{
  "action":"end_result",
  "code": "0000",
  "desc": "success",
  "sid": "ch312c0e3f63609f0900"
}

1.5 ws转写接口流程总结

sequenceDiagram
    participant Client as 客户端
    participant Server as 服务端

    Note over Client: 握手阶段
    Client->>Server: WebSocket握手请求（带签名）
    Server-->>Client: {"action": "auth_result", "code": "xxxx"} (text帧)
    
    
    Note over Client: 开始会话
    Client->>Server: {"action": "begin", ...} (text帧)
    Server-->>Client: {"action": "begin_result", "code": "xxxx"} (text帧)  
    
    Note over Client: 实时转写
    loop 持续发送音频数据
                Client->>Server: 二进制PCM音频流 (binary帧)
                Note over Client: 单声道/16bit/16kHz
                Server-->>Client: 实时转写结果{"action": "ai_result", "code": "xxxx", ...} (text帧)
                Note over Server: 有人说话时返回结果, 静音时不返回result
    end
     
     Note over Client: 音频发送完毕
            Client->>Server: {"action": "end"} (text帧)
            
            Note over Client: 会话正常结束
            Server-->>Client: 最后转写结果
            Server-->>Client: 实时转写结果{"action": "end_result", "code": "xxxx"} (text帧)
            Server->>Client: 主动断开连接

流程中任何一步服务器返回code不为0000，代表出错，服务器会异常断开ws链接，出错原因通过code错误码和desc得知

2026-03-16 15:24:59

导出PDF文档