实时语音（Realtime）

通过 WebSocket 与支持实时能力的模型建立双向会话，用于实时语音输入、语音输出和增量事件处理。它不是普通的 HTTP JSON 接口，客户端必须使用 WebSocket 协议。

连接地址

wss://www.walmind.cn/v1/realtime?model=your-realtime-model-id

鉴权可以使用 Authorization: Bearer <API_KEY>，也可以按客户端能力使用 WebSocket 子协议传递令牌。不要把 API Key 写入浏览器前端或公开页面。

Node.js 示例

import WebSocket from 'ws';

const socket = new WebSocket(
  'wss://www.walmind.cn/v1/realtime?model=your-realtime-model-id',
  {headers: {Authorization: `Bearer ${process.env.API_KEY}`}},
);

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    type: 'session.update',
    session: {modalities: ['text', 'audio']},
  }));
});

socket.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message);
});

不同实时模型使用的事件名称、音频编码和会话字段可能不同。建立连接后应先按照模型协议发送会话配置，再发送音频帧或文本事件；关闭连接时要处理服务端错误和最终响应事件。

使用前检查

• 模型列表和渠道必须明确标注支持 Realtime。
• 确认客户端使用 WebSocket，而不是 fetch 或普通 HTTP 长连接。
• 音频采样率、声道、编码和单帧大小必须符合模型要求。
• 生产环境应在服务端建立连接，避免在浏览器暴露长期 API Key。