一句话语音识别

平台通过 WebSocket 提供一句话语音识别 API（API 编码 a2t_oneshot），适用于客服对话、语音指令、短句录入等时长较短的实时识别场景，单次会话默认识别时长上限约 25 秒。

支持中间结果（variable）与最终结果（fixed）推送，便于上屏展示。
支持智能标点与后处理，提升可读性。
支持上下文与热词增强，提升专有名词、行业术语识别率。
支持多种音频编码（pcm、opus、speex、amr、adpcm），服务端统一解码为 PCM 16kHz 后识别。

使用流程

在 API Key 管理获取密钥，并写入环境变量 API_KEY。
建立 WebSocket 连接：wss://maas-api.hivoice.cn/v1/ws/asr/oneshot?model=u2-asr（详见一句话语音识别 API）。
发送文本帧 start，声明音频格式、采样率及识别参数。
循环发送二进制音频帧（与 start 中 format 一致，非 Base64）。
发送文本帧 end 结束输入（server_vad=true 且已断句时可省略）。
持续接收服务端 JSON 结果（ResultVO），直至 end=true 表示本会话结束。

start 之前发送的音频会被丢弃。布尔参数字段请传字符串 "true" / "false"。

过程示例

1. 建立连接并发送 start

Python

"""
本示例演示一句话语音识别的 WebSocket 会话。
注意：需要先将密钥写入环境变量 API_KEY；并安装 websockets：pip install websockets
"""
import asyncio
import json
import os

import websockets

API_KEY = os.environ["API_KEY"]
MODEL = "u2-asr"
TRACE_ID = "trace-demo-001"
WS_URL = (
    f"wss://maas-api.hivoice.cn/v1/ws/asr/oneshot"
    f"?model={MODEL}&trace_id={TRACE_ID}"
)

START_FRAME = {
    "type": "start",
    "request_id": TRACE_ID,
    "format": "pcm",
    "sample": "16k",
    "variable": "true",
    "punctuation": "true",
    "post_proc": "true",
    "server_vad": "false",
    "context": "请识别客服通话",
    "hotwords": ["云知声"],
}


async def run(pcm_path: str):
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(WS_URL, additional_headers=headers) as ws:
        await ws.send(json.dumps(START_FRAME))
        with open(pcm_path, "rb") as f:
            while chunk := f.read(3200):  # 约 100ms @ 16kHz 16bit mono
                await ws.send(chunk)
        await ws.send(json.dumps({"type": "end"}))
        while True:
            msg = json.loads(await ws.recv())
            print(msg)
            if msg.get("end"):
                break


if __name__ == "__main__":
    asyncio.run(run("path/to/audio.pcm"))

2. 解析识别结果

服务端以文本 JSON 帧返回 ResultVO。type=variable 为中间结果，type=fixed 为稳态片段；当 end=true 时表示本会话识别结束。

Python

# 典型中间结果
{
  "code": 0,
  "msg": "success",
  "sid": "trace-demo-001",
  "type": "variable",
  "text": "你好",
  "showText": "你好",
  "end": false
}

# 典型结束结果
{
  "code": 0,
  "msg": "success",
  "sid": "trace-demo-001",
  "type": "fixed",
  "text": "你好世界。",
  "showText": "你好世界。",
  "end": true
}

更多字段说明、音频格式与错误码，请参阅一句话语音识别 API。也可在模型体验 · 一句话语音识别中在线调试。