实时语音转写

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

WSS/v2/audio/asr/realtime

API 编码	a2t_realtime
协议	WebSocket（文本 JSON + 二进制音频）
网关路径	/v2/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}/v2/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": "..."
  }
}

会话流程

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

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

客户端消息

文本帧：start

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

typestring必填

请求阶段，固定为 start。

dataobject

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

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

formatstring

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

samplestring

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

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。

contextstring

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

hotwordsstring[ ]

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

speaker_separatestring

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

speaker_idsstring[ ]

注册声纹ID（仅当启用说话人分离时有效），最多支持10个

二进制帧：音频

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

文本帧：end

{ "type": "end" }

服务端响应

base_respobject必填

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

base_resp.status_codeinteger必填

状态码，0表示成功

base_resp.status_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 文本与上一帧相同时不重复推送
base_resp.status_code≠0 时 end=true，随后关闭连接

句末示例

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

结束示例

{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "sid": "a1b2c3d4e5f6478990abcdef12345678",
  "type": "fixed",
  "text": "",
  "end": true
}

错误码

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

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

Connect & Session

# Connect (wscat example)
wscat -c "wss://maas-api.unisound.com/v2/audio/asr/realtime?model=u2-asr" \
  -H "Authorization: Bearer <api_key>"

# Text frame: start
{
  "type": "start",
  "data": {
    "format": "opus",
    "sample": "16k",
    "variable": "true",
    "punctuation": "true",
    "post_proc": "true",
    "context": "产品名称是小云助手",
    "hotwords": ["小云","转写"]
  }
}

# Binary frames: encoded audio chunks (not Base64)

# Text frame: end
{ "type": "end" }

ResultVO

{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "sid": "a1b2c3d4e5f6478990abcdef12345678",
  "type": "variable",
  "text": "你好",
  "start_time": null,
  "end_time": null,
  "end": false
}