Skip to Content
实时语音识别

实时语音识别

WebSocket ASR
连接GET /api-ws/v1/inference
qwen-audio-3.0-asr-flash-streaming

连接与鉴权

连接 wss://api.example.com/api-ws/v1/inference,在 WebSocket 握手请求中携带平台 API Key:

Authorization: Bearer <YOUR_API_KEY>

连接建立后使用文本帧发送 JSON 控制事件,使用二进制帧发送音频。浏览器原生 WebSocket 无法设置 Authorization 请求头;网页录音需通过自己的服务端连接本接口。

启动识别任务

父节点参数类型必填说明
headeractionstring是固定为 run-task。
headertask_idstring是新的 UUID;当前任务的后续控制事件使用同一值,同一连接内不得重复使用。
headerstreamingstring是固定为 duplex。
payloadtask_groupstring是固定为 audio。
payloadtaskstring是固定为 asr。
payloadfunctionstring是固定为 recognition。
payloadmodelstring是qwen-audio-3.0-asr-flash-streaming。
payload.parametersformatstring是pcm、wav、mp3、opus、speex、aac 或 amr;须与发送的音频编码一致。
payload.parameterssample_rateinteger是正整数,与音频实际采样率一致,单位 Hz。
payload.parameterssemantic_punctuation_enabledboolean否是否启用语义标点。
payload.inputcontextarray否识别上下文;不使用时可传空数组。

连接成功后发送 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_idstring当前任务的 UUID。
header.eventstringtask-started、result-generated、task-finished 或 task-failed。
payload.output.sentence.textstring当前识别文字,可能随后更新。
payload.output.sentence.sentence_idinteger句子序号;同一句的最终结果可覆盖中间结果。
payload.output.sentence.sentence_endbooleantrue 表示该句结束。
payload.usageobject / null中间结果或完成事件中可能为 null。
payload.usage.durationnumber当前任务累计音频用量,单位秒;保留已收到的最大值,不要累加多条事件。
header.error_code / header.error_messagestringtask-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 创建识别任务。断开前已收到的识别文字应由客户端保存;连接断开后不能查询或恢复原任务的最终结果。

Last updated on