TokenHub大模型服务平台
开发指南API参考
模型价格Token Plan模型发布

实时语音转写

实时语音转写 API，基于 WebSocket 协议为长时语音场景提供稳定的流式转写服务。

WSS/v1/audio/asr/realtime
API 编码a2t_realtime
协议WebSocket（文本 JSON + 二进制音频）
网关路径/v1/audio/asr/realtime
响应体JSON

授权

Authorizationstringheader必填
HTTP: Bearer Auth
  • Security Scheme Type: http
  • HTTP Authorization Scheme: Bearer API_key，用于验证账户信息，可在 项目管理>API Key 中查看。

连接

URL

建立 WebSocket 连接时使用以下地址：

wss://{gateway-host}/v1/audio/asr/realtime?model={model_id}

Query 参数

model必填

模型编码可用选项：u2-asr。

trace_id选填

链路 ID；未传时由网关生成，并作为会话 sid

握手 Header（客户端 → 网关）

Authorization必填

Bearer {api_key}

Connection必填

Upgrade

Upgrade必填

websocket

握手失败（未建立 WebSocket）

返回 HTTP 401 / 429 等，Body 为 JSON（含 base_resp），不返回 ResultVO。

{
  "base_resp": {
    "status_code": 100001,
    "status_msg": "..."
  }
}

会话流程

  1. 建立 WebSocket
  2. 发送文本 start
  3. 循环发送二进制音频帧
  4. 发送文本 end
  5. 接收文本，直至 end=true（成功后服务端关闭连接）

start 之前发送的音频会被丢弃。

客户端消息

文本帧：start

业务参数位于 data 对象；缺省按 {}。布尔字段传字符串 "true" / "false"（大小写不敏感）。

typestring必填

请求阶段，固定为 start。

dataobject

开始识别的业务参数对象。

下列字段均位于 data 对象下。

formatstring

音频格式，默认 pcm。可选值：pcm、opus、adpcm、speex、amr。

samplestring

采样率，默认 16k。可选值：16k，也兼容 16000。

variablestring

是否返回可变结果，默认 true。可选值：true、false。

punctuationstring

是否开启标点，默认 true。可选值：true、false。

post_procstring

是否将数字转为阿拉伯数字，默认 true。可选值：true、false。

max_start_silencestring

开始最大静音时长，单位 ms。可选值：正整数；在 200~2000 范围内生效。

max_end_silencestring

结束最大静音时长，单位 ms，默认 500。可选值：200~2000。

contextstring

上下文，用于指定模型的上下文信息。可选值：长度限制 500 字。

hotwordsstring[ ]

热词列表。可选值：最多 200 条，每个热词不超过 5 个字符。

speaker_separatestring

是否开启说话人分离，默认 false。可选值：true 使用 Yama 引擎；false 使用流式 Stream 引擎。

二进制帧：音频

  • 类型: WebSocket Binary
  • 内容: 与 start.data.format 一致的编码音频分片（非 Base64）
  • 时机: 时机：start 成功之后、end 之前

文本帧：end

{ "type": "end" }

服务端响应

codeinteger必填

0 表示成功

msgstring必填

成功为 success

sidstring必填

会话 ID，等于 trace_id

typestring

variable（中间结果）/ fixed（稳态或句末）

textstring

当前片段文本

start_timelong

句内开始时间（ms）；type=variable 时为 null

end_timelong

句内结束时间（ms）；type=variable 时为 null

wordInfoarray

词边界，type=fixed时下发

speakerstring

仅start传入speaker_separate=true且type=fixed时下发

endboolean必填

true 表示本轮识别结束

推送规则

  • variable=false 时不推送 type=variable
  • text 为空且 end=false 时不推送
  • variable=true 且 variable 文本与上一帧相同时不重复推送
  • code≠0 时 end=true，随后关闭连接

句末示例

{
  "code": 0,
  "msg": "success",
  "sid": "a1b2c3d4e5f6478990abcdef12345678",
  "type": "fixed",
  "text": "你好世界",
  "start_time": 0,
  "end_time": 1200,
  "end": false
}

结束示例

{
  "code": 0,
  "msg": "success",
  "sid": "a1b2c3d4e5f6478990abcdef12345678",
  "type": "fixed",
  "text": "",
  "end": true
}

错误码

网关握手失败见「连接」章节，不返回 ResultVO。

业务错误码业务描述信息解决方法
203001param error:xx检查参数
203002idle timeout error: xx连接空闲超时
203003server internal error: xx请联系客服，并提工单并提供request_id
203004process error:: xx请联系客服，并提工单并提供request_id
203005decode error: xx音频解码失败