实时语音识别
连接与鉴权
连接 wss://api.example.com/api-ws/v1/inference,在 WebSocket 握手请求中携带平台 API Key:
Authorization: Bearer <YOUR_API_KEY>连接建立后使用文本帧发送 JSON 控制事件,使用二进制帧发送音频。浏览器原生 WebSocket 无法设置 Authorization 请求头;网页录音需通过自己的服务端连接本接口。
启动识别任务
| 父节点 | 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
header | action | string | 是 | 固定为 run-task。 |
header | task_id | string | 是 | 新的 UUID;当前任务的后续控制事件使用同一值,同一连接内不得重复使用。 |
header | streaming | string | 是 | 固定为 duplex。 |
payload | task_group | string | 是 | 固定为 audio。 |
payload | task | string | 是 | 固定为 asr。 |
payload | function | string | 是 | 固定为 recognition。 |
payload | model | string | 是 | qwen-audio-3.0-asr-flash-streaming。 |
payload.parameters | format | string | 是 | pcm、wav、mp3、opus、speex、aac 或 amr;须与发送的音频编码一致。 |
payload.parameters | sample_rate | integer | 是 | 正整数,与音频实际采样率一致,单位 Hz。 |
payload.parameters | semantic_punctuation_enabled | boolean | 否 | 是否启用语义标点。 |
payload.input | context | array | 否 | 识别上下文;不使用时可传空数组。 |
连接成功后发送 run-task 文本帧:
{
"header": {
"action": "run-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-123456789abc",
"streaming": "duplex"
},
"payload": {
"task_group": "audio",
"task": "asr",
"function": "recognition",
"model": "qwen-audio-3.0-asr-flash-streaming",
"parameters": {
"format": "pcm",
"sample_rate": 16000
},
"input": { "context": [] }
}
}收到 task-started 后再发送音频:
{
"header": {
"task_id": "2bf83b9a-baeb-4fda-8d9a-123456789abc",
"event": "task-started"
},
"payload": {}
}发送音频
将麦克风采集的音频或本地文件内容分片,持续发送 WebSocket 二进制消息,同时接收识别事件。使用单声道音频,每条消息最大 1 MiB。
例如发送 16 kHz、16 bit、单声道 PCM 时,将 format 设为 pcm、sample_rate 设为 16000。WAV 应包含 PCM 音频;Opus 和 Speex 使用 Ogg 容器,AMR 使用 AMR-NB。若源文件为 M4A,先在客户端转换,不能仅修改扩展名或将原文件字节标为 pcm。
ffmpeg -i recording.m4a -vn -ac 1 -ar 16000 -c:a pcm_s16le sample.wav接收识别结果
| 字段 | 类型 | 说明 |
|---|---|---|
header.task_id | string | 当前任务的 UUID。 |
header.event | string | task-started、result-generated、task-finished 或 task-failed。 |
payload.output.sentence.text | string | 当前识别文字,可能随后更新。 |
payload.output.sentence.sentence_id | integer | 句子序号;同一句的最终结果可覆盖中间结果。 |
payload.output.sentence.sentence_end | boolean | true 表示该句结束。 |
payload.usage | object / null | 中间结果或完成事件中可能为 null。 |
payload.usage.duration | number | 当前任务累计音频用量,单位秒;保留已收到的最大值,不要累加多条事件。 |
header.error_code / header.error_message | string | task-failed 事件中的错误码和说明。 |
result-generated 包含中间文字或最终句。以下示例为最终句:
{
"header": {
"task_id": "2bf83b9a-baeb-4fda-8d9a-123456789abc",
"event": "result-generated"
},
"payload": {
"output": {
"sentence": {
"text": "你好。",
"sentence_end": true,
"sentence_id": 1
}
},
"usage": { "duration": 3 }
}
}结束识别任务
停止发送音频后,发送 finish-task 文本帧:
{
"header": {
"action": "finish-task",
"task_id": "2bf83b9a-baeb-4fda-8d9a-123456789abc",
"streaming": "duplex"
},
"payload": { "input": {} }
}继续接收事件,直到 task-finished。完成事件的 payload.usage 可能为 null,此时保留之前收到的累计时长。一个连接可顺序执行多个任务,每次使用新的 UUID;不能并发复用同一连接。直接断开可能丢失最终结果,且已产生的用量仍可能计费;接口不提供断开后的任务结果查询。
调用示例
安装 websockets 14+,设置 ASR_API_KEY 环境变量。示例使用 Python 3.11+,读取 16 kHz、16 bit、单声道 WAV,发送其中的 PCM 数据;发送音频与接收结果同时进行。
import asyncio
import json
import os
import uuid
import wave
import websockets
async def send_audio(ws, path, task_id):
with wave.open(path, "rb") as audio:
if (audio.getnchannels(), audio.getsampwidth(), audio.getframerate()) != (1, 2, 16000):
raise ValueError("需要单声道、16 bit、16 kHz WAV 文件")
while chunk := audio.readframes(1600):
await ws.send(chunk)
await asyncio.sleep(len(chunk) / 32000)
await ws.send(json.dumps({
"header": {"action": "finish-task", "task_id": task_id, "streaming": "duplex"},
"payload": {"input": {}},
}))
async def receive_results(ws):
sentences = {}
duration = None
while True:
event = json.loads(await asyncio.wait_for(ws.recv(), timeout=60))
kind = event.get("header", {}).get("event")
if kind == "task-failed":
raise RuntimeError(event["header"])
payload = event.get("payload") or {}
sentence = (payload.get("output") or {}).get("sentence") or {}
if kind == "result-generated" and sentence.get("sentence_end") and not sentence.get("heartbeat"):
sentences[sentence["sentence_id"]] = sentence.get("text", "")
usage = payload.get("usage")
if usage is not None:
reported = usage.get("duration")
if isinstance(reported, (int, float)):
duration = reported if duration is None else max(duration, reported)
if kind == "task-finished":
print("".join(sentences[key] for key in sorted(sentences)))
print(f"累计音频秒数:{duration if duration is not None else '未返回'}")
return
async def recognize(path):
task_id = str(uuid.uuid4())
headers = {"Authorization": f"Bearer {os.environ['ASR_API_KEY']}"}
async with websockets.connect(
"wss://api.example.com/api-ws/v1/inference", additional_headers=headers
) as ws:
await ws.send(json.dumps({
"header": {"action": "run-task", "task_id": task_id, "streaming": "duplex"},
"payload": {
"task_group": "audio", "task": "asr", "function": "recognition",
"model": "qwen-audio-3.0-asr-flash-streaming",
"parameters": {"format": "pcm", "sample_rate": 16000},
"input": {"context": []},
},
}))
started = json.loads(await asyncio.wait_for(ws.recv(), timeout=30))
if started.get("header", {}).get("event") != "task-started":
raise RuntimeError(started)
async with asyncio.TaskGroup() as tasks:
tasks.create_task(send_audio(ws, path, task_id))
tasks.create_task(receive_results(ws))
asyncio.run(recognize("sample.wav"))错误处理
握手失败时检查 HTTP 状态和 API Key。连接建立后,task-failed 在 header.error_code、header.error_message 返回错误;收到该事件应停止发送音频,关闭连接,重新调用时使用新的任务 ID。
{
"header": {
"event": "task-failed",
"task_id": "2bf83b9a-baeb-4fda-8d9a-123456789abc",
"error_code": "QuotaExhausted",
"error_message": "Insufficient quota for ASR."
},
"payload": {}
}header.error_code | 处理建议 |
|---|---|
InvalidParameter | 检查任务 ID、音频格式、采样率和事件顺序。 |
AccessDenied | 检查 API Key 状态及模型权限。 |
QuotaExhausted | 检查账户与 API Key 额度。 |
Throttling | 降低任务频率,稍后重试。 |
ModelNotSupported | 核对模型名及可用性。 |
ModelPriceNotConfigured | 联系平台检查定价。 |
InternalError | 保存任务 ID 和错误事件,稍后重试或联系平台。 |
常见问题
本地音频文件可以转写吗?
可以。读取本地文件并按 parameters.format 指定的编码发送二进制音频帧;与麦克风音频使用同一个 WebSocket 接口。上面的示例读取 WAV 文件中的 PCM 数据。
连接中断后如何继续?
重新建立连接,并使用新的 UUID 创建识别任务。断开前已收到的识别文字应由客户端保存;连接断开后不能查询或恢复原任务的最终结果。