原子能力接入（WebSocket）

更新时间：2026-10-19

实时语音转写（WebSocket）

接口描述

通过 WebSocket 协议提供实时语音转写：客户端建立连接后，按 START → AUDIO → FINISH 顺序发送文本 JSON 帧，服务端实时返回转写结果。一条连接内支持三类输入帧（START / AUDIO / FINISH），输出 result / silence / echo / error 四类事件帧。

对外统一供应商标识为 baidurtc-asr，具体识别引擎由 START 帧的 app_id 在部署侧映射决定，客户端无需感知。

请求语法

Http

1GET /v1/asr HTTP/1.1
2Host: rtc-aiagent.baidubce.com
3Upgrade: websocket
4Connection: Upgrade
5Authorization: Bearer bce-v3/ALTAK-xxx

请求头域

名称	说明
Authorization	必填。鉴权头，格式`Bearer bce-v3/ALTAK-xxx`，一个 `app_id` 对应一个 `apikey`。缺失或无效返回 401。

请求参数（START 帧 data）

建连后首帧，声明供应商、业务 app_id 与各可选能力。

名称	类型	是否必选	参数位置	描述
provider	String	是	START.data	固定`baidurtc-asr`，具体引擎由部署侧配置与 `app_id` 绑定
app_id	String	否	START.data	业务标识（顶层字段）。用于网关越权校验、ASR Server 引擎路由、声纹索引。须与鉴权`apikey` 归属一致，否则 403
3a	Object	否	START.data	云端 3A（噪声抑制/自动增益），见下方子表
voiceprint	Object	否	START.data	声纹识别，见下方子表
security_review	Object	否	START.data	输入安全审核，见下方子表
vad	Object	否	START.data	VAD 断句参数，见下方子表
asr	Object	否	START.data	ASR 引擎参数（热词），见下方子表

云端 3A（3a）子表

名称	类型	是否必选	参数位置	描述
ans	Object	否	START.data.3a	噪声抑制（ANS）配置
+enable	Boolean	否	START.data.3a.ans	是否启用噪声抑制，默认 true
+pre_mode	String	否	START.data.3a.ans	前置线性降噪模式 N/L/M/H/VH（禁用/低/中/高/极高），默认 N
+mid_gain_db	Float	否	START.data.3a.ans	前置降噪后附加固定增益（db），默认 0，范围 [0.0, 15.0]
+df_limit_db	Float	否	START.data.3a.ans	模型降噪抑制强度（db），默认 75，范围 [0.0, 95.0]
agc	Object	否	START.data.3a	自动增益（AGC）配置
+enable	Boolean	否	START.data.3a.agc	是否启用自动增益，默认 false
+max_volume	Integer	否	START.data.3a.agc	增益后峰值音量上限，默认 60，范围 [1, 100)
+extra_gain	Double	否	START.data.3a.agc	增益后额外固定增益（db），默认 0，范围 [0, 3)
echo	Boolean	否	START.data.3a	是否回传 echo 帧（处理前 raw + 处理后 final，各阶段音频仅启用时才有），默认 false。仅 echo=true 时返回，与 3A 是否开启无关

声纹识别（voiceprint）子表

名称	类型	是否必选	参数位置	描述
enable	Boolean	否	START.data.voiceprint	是否启用声纹识别，默认 false
user_id	String	enable 时必填	START.data.voiceprint	声纹注册时输入的 user_id，声纹注册说明见 https://cloud.baidu.com/doc/RTC/s/hm8zjic1q#注册用户声纹信息

输入安全审核（security_review）子表

名称	类型	是否必选	参数位置	描述
enable	Boolean	否	START.data.security_review	是否启用输入安全审核，默认 false

VAD 断句参数（vad）子表

名称	类型	是否必选	参数位置	描述
vad_ms	Integer	否	START.data.vad	静音多长（ms）算一句话结束，默认 800，范围 [200, 10000]
vad_wait_ms	Integer	否	START.data.vad	断句后多久（ms）内新句粘回上一句，默认 1500，范围 [200, 10000]

ASR 引擎参数（asr）子表

名称	类型	是否必选	参数位置	描述
hot_words	Array<String>	否	START.data.asr	热词列表，提升特定词识别率

请求示例

START 帧（声明供应商与各可选能力，均可缺省）

                JSON
                
            

                {
  "type": "START",
  "data": {
    "provider": "baidurtc-asr",
    "app_id": "your-app-id",
    "3a": {
      "ans": { "enable": true, "pre_mode": "N", "mid_gain_db": 0, "df_limit_db": 75 },
      "agc": { "enable": false, "max_volume": 60, "extra_gain": 0 },
      "echo": false
    },
    "voiceprint": { "enable": true, "user_id": "u123" },
    "security_review": { "enable": true },
    "vad": { "vad_ms": 800, "vad_wait_ms": 1500 },
    "asr": { "hot_words": ["hello", "BRTC"] }
  }
}
            

AUDIO 帧（音频，PCM 经 base64 编码）

                JSON
                
                {"type":"AUDIO","data":{"audio":"<base64 编码的 PCM 字节流>","seq":1}}

名称	类型	是否必选	描述
type	String	是	固定`AUDIO`
data	Object	是	帧数据
+audio	String	是	base64 编码的 PCM 字节流
+seq	Integer	否	帧序号，从 1 单调递增，用于乱序检测与 echo 关联（重复/回退仅告警，不拒绝）

FINISH 帧（结束，服务端 drain 剩余结果后主动关闭）

                JSON
                
                {"type":"FINISH"}

响应参数

输出事件统一带 type 字段区分四类：result / silence / echo / error。

result 帧（转写结果）

名称	类型	描述
type	String	固定`result`
text	String	累积后的转写文本（非增量 delta），可能带前缀标记（见下方说明）
is_final	Boolean	是否这一句完整（false=中间结果，true=该句完整）
extra_info	Object	可选能力附加结果，无值时整体省略
+emotion	Object	情绪识别结果
++label	String	情绪标签
+speaker	Object	说话人识别结果
++speaker_id	String	说话人 person_id（稳定唯一）
++speaker_name	String	说话人展示名（可重名）
++score	Float	相似度（0~1）
+security_review	Object	安全审核结果
++is_blocked	Boolean	true=审核拦截（文本照发+标记），false=通过

extra_info 及内部字段全部「有值才带」，无值整体省略；中间结果通常不带。text 前缀标记：[M]: 中间结果 / [M]:[C]: 粘句中间结果 / [C]: 粘句续写的最终结果（应替换上一条 final）/ 无前缀正常 final。

silence 帧（静音边沿，成对触发）

名称	类型	描述
type	String	固定`silence`
data	Object	帧数据
+is_silence	Boolean	true=进入静音，false=恢复说话
+seq	Integer	触发该边沿的 AUDIO 帧 seq（有值才带）

echo 帧（音频处理前后回传，3a.echo=true 时生效，可丢弃）

名称	类型	描述
type	String	固定`echo`
data	Object	帧数据
+seq	Integer	对应输入 AUDIO 帧的 seq
+raw	String	3A 前原始音频（base64，恒有）
+ans	String	ANS 后音频（ANS 启用时才有）
+agc	String	AGC 后音频（AGC 启用时才有）
+final	String	全链路 3A 后音频（送入 ASR 引擎的最终音频）

error 帧（异常）

名称	类型	描述
type	String	固定`error`
code	Integer	错误码（见「错误码」节）
message	String	错误描述（脱敏，不回显 token/上游地址等内部信息）
retryable	Boolean	是否可重试

响应示例

result 帧

                JSON
                
            

                {
  "type": "result",
  "text": "你好，今天天气不错",
  "is_final": true,
  "extra_info": {
    "emotion": { "label": "快乐" },
    "speaker": { "speaker_id": "p123", "speaker_name": "张三", "score": 0.8523 },
    "security_review": { "is_blocked": false }
  }
}
            

silence 帧

                JSON
                
                {"type":"silence","data":{"is_silence":true}}
{"type":"silence","data":{"is_silence":false,"seq":42}}

echo 帧

                JSON
                
            

                {
  "type": "echo",
  "data": {
    "seq": 1,
    "raw": "<base64 PCM（3A 前）>",
    "ans": "<base64 PCM（ANS 后）>",
    "agc": "<base64 PCM（AGC 后）>",
    "final": "<base64 PCM（全链路 3A 后）>"
  }
}
            

error 帧

                JSON
                
                {"type":"error","code":504,"message":"upstream did not return final result in time","retryable":true}

错误码

错误分三层：HTTP 握手错误（WS 升级前返回）、网关 error 帧、ASR Server error 帧（经网关透明透传）。

HTTP 握手错误（WS 升级前）

状态码	error 字段	含义
401	unauthorized	缺失或无效的 Bearer token
404	capability_not_found	未知能力（路径非`/v1/asr`）
429	too_many_connections / rate_limited	连接数超限 / IP 限流

网关 error 帧

code	含义	retryable
400	帧过大（超 MaxMessageSize）/ 二进制帧不被 ASR 接受	否
403	app_id 越权不匹配（START 首帧 app_id ≠ 鉴权 app_id）	否
408	应用帧空闲超时（默认 60s 无应用帧）	否
502	上游未配置 / 上游拨号失败	是
503	熔断打开 / 上游异常关闭 / 上游连接丢失	是
529	过载（写队列持续满载）/ 最大连接时长到	否

ASR Server error 帧（网关透明透传）

code	含义	retryable
400	参数/帧序错误（重复 START、未知 provider、缺 START、audio 空/超大/非法 base64、FINISH 后发 AUDIO 等）	否
503	上游重连耗尽	是
504	FINISH 后上游未返回最终结果 / 上游关闭但无任何 final	是

音频规格

项	值
编码	PCM（线性，无压缩）
采样率	16kHz
位深	16bit
声道	单声道
字节序	小端（LE）
单帧上限	10s 音频（320000 字节原始 PCM），AUDIO 帧适用

分片由客户端决定（建议每帧 20~100ms，即 640~3200 字节原始 PCM），帧间连续拼接即完整 PCM 流。音频规格固定，START 帧无需声明 format/sample 字段。

评价此篇文章

有帮助没帮助

原子能力接入（SSE）

客户端SDK

百度智能云

RTC 实时音视频