一句话语音识别

一句话语音识别 API，基于 WebSocket 协议为短语音场景提供低延迟的实时识别服务。
WSS/v2/ws/asr/oneshot
API 编码a2t_oneshot
协议WebSocket（文本 JSON + 二进制音频）
网关路径/v2/ws/asr/oneshot
响应体JSON

授权

Authorizationstringheader必填
HTTP: Bearer Auth

连接

URL

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

wss://{gateway-host}/v2/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。

enable_auto_langstring

是否开启语种自动识别，默认 false。可选值：true、false。

languagestring

指定语种。可选值：
  • zh-CN (中文)
  • en-US (英语)
  • ar-SA (阿拉伯语)
  • de-DE (德语)
  • es-MX (西班牙语)
  • fr-FR (法语)
  • id-ID (印尼语)
  • ja-JP (日语)
  • ko-KR (韩语)
  • pt-BR (葡萄牙语)
  • ru-RU (俄语)
  • tr-TR (土耳其语)
  • vi-VN (越南语)
  • th-TH (泰语)
  • it-IT (意大利语)

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[ ]

热词列表。可选值：最多 500 条，每个热词不超过 5 个汉字或英文单词。

二进制帧：音频

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

文本帧：end

{
  "type": "end"
}

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

服务端响应

base_respobject必填

本次请求的状态码及其详情

base_resp.status_codeinteger必填

状态码，0表示成功

base_resp.status_msgstring必填

状态详情，成功为 success

sidstring必填

等于 request_id

typestring

识别结果类型：fixed / variable

textstring

当前片段文本

varTextstring

可变文本

showTextstring

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

endboolean必填

true 表示本会话识别结束

server_vadboolean必填

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

vad_countinteger必填

断句计数

resultNuminteger必填

结果序号，从 1 递增

languagestring

识别语种，仅 type=fixed 时下发。取值与请求参数 language 一致。

结束示例

{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "sid": "trace-abc-001",
  "type": "fixed",
  "text": "你好世界。",
  "showText": "你好世界。",
  "end": true,
  "server_vad": false,
  "vad_count": 0,
  "resultNum": 2,
  "language": "zh-CN"
}

错误码

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