实时语音转文字（Realtime ASR）

Realtime ASR（WebSocket 实时语音转文字）

1. 接口概述

Realtime ASR 使用 WebSocket 建立长连接。客户端持续发送音频切片（PCM bytes → Base64），服务端实时返回增量识别（partial）与最终识别（committed）结果；可选返回词级时间戳。

协议：WebSocket
接口：wss://openapi.myvocal.ai/asr/realtime

2. 连接参数（URL Query）

2.1 参数表

参数名	类型	必填	默认值参数	说明
`api-key`	string	是	-	API Key（放在 URL query）
`model_id`	string	否	`echo_v1_realtime`	模型 ID
`audio_format`	string	否	`pcm_16000`	音频格式（见 2.3）
`commit_mode`	string	否	`vad`	提交模式：`vad` / `manual`（见第 5 节）
`word_timestamps`	boolean	否	`false`	是否返回词级时间戳
`language`	string	否	省略=auto	语言代码；`Language=""` 时不会写入 URL（表示 auto）

2.2 `language`

自动识别：不要传 language 参数
指定语言：传 language=xx（例如 en / zh / ja）
点击查看支持语言列表

2.3 `audio_format` 支持（PCM 16-bit 单声道）

pcm_8000
pcm_16000
pcm_22050
pcm_24000
pcm_44100

3. 连接示例

3.1 默认推荐（自动识别语言：不带 language）

wss://openapi.myvocal.ai/asr/realtime?api-key=YOUR_KEY&model_id=echo_v1_realtime&audio_format=pcm_16000&commit_mode=vad&word_timestamps=false

3.2 指定语言（例如日语）

wss://openapi.myvocal.ai/asr/realtime?api-key=YOUR_KEY&model_id=echo_v1_realtime&audio_format=pcm_16000&commit_mode=vad&word_timestamps=false&language=jpn

支持语言列表及WER数据

3.3 手动提交模式（manual）

wss://openapi.myvocal.ai/asr/realtime?api-key=YOUR_KEY&model_id=echo_v1_realtime&audio_format=pcm_16000&commit_mode=manual&word_timestamps=true

4. 上行协议（Client → Server）

4.1 默认上行

字段名	类型	必填	说明
`message_type`	string	是	固定为 `input_audio_chunk`
`audio_base_64`	string	是	音频 PCM bytes 的 Base64
`sample_rate`	integer	是	与 `audio_format` 对应（如 `pcm_16000` → 16000）
`commit`	boolean	是	是否提交（manual 模式句末 true；vad 模式通常 false 发送即可）
`previous_text`	string	否	上下文文本，仅允许在本 WebSocket 会话的第一帧音频中传入。第二帧及之后传入会返回 `input_error`。

示例：普通音频帧

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "BASE64_PCM_BYTES...",
  "sample_rate": 16000,
  "commit": false
}

示例：首帧携带上下文文本

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "BASE64_PCM_BYTES...",
  "sample_rate": 16000,
  "commit": false,
  "previous_text": "上一句上下文：客户正在确认是否会还款。"
}

注意：previous_text 只用于首帧上下文增强。后续音频帧不要继续携带该字段。

4.2 可选上行（WireProtocolSimple）

当配置 WireProtocolSimple 时，上行只发送：

audio_base_64
sample_rate

注意：该模式 不包含 message_type 和 commit 字段，适用于“服务端不要求 message_type/commit”的兼容场景。
如需使用 previous_text，请使用默认上行协议；WireProtocolSimple 模式不支持传入 previous_text。

示例：WireProtocolSimple 音频帧

{
  "audio_base_64": "BASE64_PCM_BYTES...",
  "sample_rate": 16000
}

5. 提交策略（commit_mode）

5.1 `commit_mode=vad`（默认）

客户端持续发送音频帧
服务端自动判定一句话结束并返回最终结果
客户端无需额外“提交消息”（仍可持续发送 commit=false 的音频帧）

5.2 `commit_mode=manual`

客户端持续发送音频帧：commit=false
在你判定一句结束时：发送最后一帧音频并设置 commit=true

示例：句末提交（manual）

{
  "message_type": "input_audio_chunk",
  "audio_base_64": "BASE64_PCM_BYTES_LAST...",
  "sample_rate": 16000,
  "commit": true
}

6. 下行协议（Server → Client）

服务端返回 JSON，根据 message_type 分发回调。

6.1 会话建立：`session_started`

{
  "message_type": "session_started",
  "session_id": "xxxx"
}

6.2 增量识别：`partial_transcript`

{
  "message_type": "partial_transcript",
  "text": "hello wor..."
}

6.3 最终结果：`committed_transcript`

{
  "message_type": "committed_transcript",
  "text": "hello world"
}

6.4 最终结果（带词级时间戳）：`committed_transcript_with_timestamps`

当 URL 参数 word_timestamps=true 时，最终结果可能返回 words：

{
  "message_type": "committed_transcript_with_timestamps",
  "text": "hello world",
  "words": [
    { "word": "hello", "start": 0.12, "end": 0.42 },
    { "word": "world", "start": 0.50, "end": 0.86 }
  ]
}

7. 错误返回（Server → Client）

统一按 ErrorMessage 结构处理以下 message_type：

error
auth_error
quota_exceeded_error
unaccepted_terms
input_error

示例：鉴权失败

{
  "message_type": "auth_error",
  "error": "Invalid API key"
}

示例：额度不足

{
  "message_type": "quota_exceeded_error",
  "error": "Quota exceeded"
}

示例：previous_text 不在第一帧传入

{
  "message_type": "input_error",
  "error": "previous_text can only be set on the first audio chunk"
}

8. 连接握手与超时（默认）

HandshakeTimeout：默认 10 秒（Config 不设置或 <=0 时）
WSURL：必填（不填会报错）

9. 最佳实践

使用长连接持续推流，降低握手开销；
音频建议切片（20ms~200ms）降低延迟；
manual 模式务必在句末发送 commit=true 才会产生最终结果；
自动识别语言时不要传 language（省略即 auto）；
如需传入文本上下文，使用 previous_text，且只放在第一帧 input_audio_chunk 中；不要放在 URL Query，也不要每一帧重复传。

10. 计费说明

Realtime 按音频推流时长计费，计费单位为秒

实时识别增强参数

以下参数用于控制语言识别信息和关键词提示。所有参数均为可选。

URL 示例：

wss://openapi.myvocal.ai/asr/realtime?api-key={YOUR_API_KEY}&model_id=echo_v1_realtime&audio_format=pcm_16000&commit_strategy=manual&include_language_detection=true&keyterms=锦江国际城

keyterms 建议优先放入品牌名、地名、产品名或业务术语，并控制词表规模。