Skip to main content

实时语音转写

千问办公企业旗舰版开发者文档:实时语音转写。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:GET/api/openapi/app/v1/sessions/voice-input/stream
通过 WebSocket 将麦克风音频转为输入框草稿。不需要 session_id,不创建会话或执行 Agent 回合。 浏览器通过认证接入中的 createAppWebSocket 建立连接,例如 await createAppWebSocket('/api/openapi/app/v1/sessions/voice-input/stream?language=zh')。后续音频和控制消息保持下述协议。

请求参数

参数位置类型必填说明
languagequerystring否zh 或 en;省略或空字符串由服务端默认处理,只能出现一次
必须升级为 WebSocket。禁止额外查询参数,包括 token、用户 ID 和组织 ID。仅支持人类用户身份,客户管理 API Key 和 Agent 身份不能替代用户登录态。

音频和控制消息

成功握手返回 HTTP 101。之后发送无文件头的二进制音频:单声道、16 kHz、有符号 16 位小端 PCM。每条消息非空、字节数为偶数,最大 64 KiB。按设备实际采样率重采样,MediaRecorder 产生的 WebM/Opus 不能直接发送。 停止采集后先发送剩余 PCM,再发送一次文本消息:
{"type":"finish"}
此后不再发送音频或重复 finish,继续接收结果。单次连接最长 10 分钟,服务端凭据更早到期时提前结束;长期无消息也会超时。限制客户端发送缓冲,网络阻塞时结束本次录音,不自动重放音频。

服务端事件

事件均为 JSON 文本消息。
type字段客户端处理
previewindex、text按索引替换分段预览,不能追加;空文本也必须替换
finalindex、text保存分段最终文本,覆盖预览;单段完成不代表整次录音完成
finished无已发送 finish 且全部已识别分段完成,整次转写成功
errorcode当前错误码为 transcription_failed,丢弃本次未完成结果
index 从 0 开始,省略表示 0;text 省略表示空字符串。例如:
{"type":"preview","text":"明天下午"}
{"type":"final","text":"明天下午三点开会。"}
{"type":"finished"}
只有 finished 才是成功信号,正常关闭连接也不能替代它。提前断线、超时或 error 时,不把局部 final 或预览插入输入框,也不调用润色;网络故障时可能收不到 error。

连接事件处理示例

下面演示已按认证接入建立连接后的事件处理。调用方负责麦克风授权、PCM 采集、重采样和临时预览渲染;等待 onopen 后才上传音频。
// ws 为调用方按认证接入建立的连接;握手参数 language=zh。
const segments = new Map();
let finishing = false, completed = false, invalid = false, timer;
function cancel() {
  invalid = true;
  clearTimeout(timer);
  segments.clear();
  ws.close();
  // 同时停止麦克风,取消润色请求并清除临时预览。
}
ws.onmessage = ({ data }) => {
  if (invalid || completed) return;
  try {
    const event = JSON.parse(data);
    if (event.type === 'error') return cancel();
    if (event.type === 'preview' || event.type === 'final') {
      segments.set(event.index ?? 0, {
        text: event.text ?? '', final: event.type === 'final',
      });
    } else if (event.type === 'finished') {
      if (!finishing || [...segments.values()].some((s) => !s.final)) return cancel();
      completed = true;
      clearTimeout(timer);
      const text = [...segments.entries()].sort(([a], [b]) => a - b)
        .map(([, s]) => s.text).join('');
      ws.close();
      // text 非空时才可润色;插入前核对会话和输入框版本。
    }
  } catch { cancel(); }
};
ws.onerror = cancel;
ws.onclose = () => { if (!completed) cancel(); };
function sendPCM(bytes) {
  if (invalid || completed || finishing || ws.readyState !== WebSocket.OPEN) return false;
  if (!bytes.byteLength || bytes.byteLength % 2 || bytes.byteLength > 65536 ||
      ws.bufferedAmount > 1024 * 1024) { cancel(); return false; }
  ws.send(bytes);
  return true;
}
function finish() {
  if (invalid || completed || finishing) return;
  if (ws.readyState !== WebSocket.OPEN) return cancel();
  finishing = true;
  ws.send(JSON.stringify({ type: 'finish' }));
  timer = setTimeout(cancel, 20000);
}
finish 前停止采集并上传剩余 PCM,之后等待完整结果。sendPCM 返回 false 时停止上传。取消、编辑输入框或切换会话时停止麦克风、关闭连接并丢弃迟到结果。需要重试时由用户重新开始录音,不恢复旧连接或重放 PCM。

错误处理

阶段状态或事件说明
升级前400非 WebSocket 请求、无效语言、重复或额外查询参数等
升级前401 / 403登录失效、无权访问或身份类型不支持
升级前503转写依赖或初始化不可用
升级后error 或提前关闭协议错误、上游失败、超时等,本次转写未完成