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

一句话语音识别

一句话语音识别 API，基于 WebSocket 协议为短语音场景提供低延迟的实时识别服务。

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

授权

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

连接

URL

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

wss://{gateway-host}/v1/ws/asr/oneshot?model={model_id}

Query 参数

model必填

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

trace_id选填

链路 ID；未传时由网关生成，并作为默认 request_id

握手 Header（客户端 → 网关）

Authorization必填

Bearer {api_key}

Connection必填

Upgrade

Upgrade必填

websocket

握手失败（未建立 WebSocket）

返回 HTTP 状态码 401 / 429 等

会话流程

  1. 建立 WebSocket
  2. 发送文本 start
  3. 循环发送二进制音频帧
  4. 发送文本 end（server_vad=true 且已断句时可选）
  5. 接收文本，直至 end=true

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

客户端消息

文本帧：start

根对象为扁平 JSON（无 data 嵌套）。布尔字段传字符串 "true" / "false"（大小写不敏感）。

typestring必填

请求阶段，固定为 start。

request_idstring

会话 ID，响应 sid 与其保持一致；别名 requestId，未传时默认复用 trace_id。

formatstring

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

samplestring

采样率，默认 16k。可选值：16k。

variablestring

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

punctuationstring

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

post_procstring

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

server_vadstring

是否开启智能断句，默认 false。可选值：true、false。

max_start_silencestring

开始最大静音时长，单位 ms，默认 2000。可选值：正整数。

max_end_silencestring

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

contextstring

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

hotwordsstring[ ]

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

二进制帧：音频

  • 类型: WebSocket Binary
  • 内容: 与 start.format 一致的编码音频分片（非 Base64）
  • 解码: 服务端转为 PCM 16kHz 单声道后送识别引擎

文本帧：end

{
  "type": "end"
}

仅支持 start、end；其它 type 返回参数错误。

服务端响应

codeinteger必填

0 表示成功

msgstring必填

成功为 success

sidstring必填

等于 request_id

typestring

识别结果类型：fixed / variable

textstring

当前片段文本

varTextstring

可变文本

showTextstring

上屏文案（历史 fixed + 当前片段）

endboolean必填

true 表示本会话识别结束

server_vadboolean必填

true 表示智能断句触发的句末结果

vad_countinteger必填

断句计数

resultNuminteger必填

结果序号，从 1 递增

结束示例

{
  "code": 0,
  "msg": "success",
  "sid": "trace-abc-001",
  "type": "fixed",
  "text": "你好世界。",
  "showText": "你好世界。",
  "end": true,
  "server_vad": false,
  "vad_count": 0,
  "resultNum": 2,
}

错误码

业务错误码业务描述信息解决方法
202001param error:xx检查参数
202002idle timeout error: xx连接空闲超时
202003server internal error: xx请联系客服，并提工单并提供request_id
202004asr timeout error: xx识别超时（默认上限 600000 ms）
202005decode error: xx音频解码失败