MiniCPM-o Docs
Realtime API

Realtime API 概览

MiniCPM-o Realtime API 当前公开 WebSocket 协议

MiniCPM-o Realtime API 通过一个 WebSocket 入口提供 turn-based chat、视频全双工和音频全双工三种模式。 公网客户端直接连接 MAP API。演示网站用于页面、文档与分享,不作为客户端的推理 API 地址。自建 Gateway/Worker 的内部架构见架构文档。

API Host

https://api.modelbest.cn

连接端点

wss://api.modelbest.cn/v1/realtime?mode={chat|video|audio}&model=MiniCPM-o-4.5-Realtime
参数必填说明
mode建议显式传入可选 chat、video、audio
model是(MAP)固定为 MiniCPM-o-4.5-Realtime

session_id 是服务端返回的不透明字符串,客户端不需要在 URL 中传入,也不应该假设它的格式。

获取 API Key 与鉴权

在 MAP 国内控制台 申请自己的 API Key,配合 api.modelbest.cn 使用。 海外服务使用 api.modelbest.ai,对应 海外控制台。Key 与服务区域应匹配。 教程中的 YOUR_API_KEY 必须替换为你申请的 Key;不要使用演示页面的共享 Key 作为应用凭证。

服务端客户端在 WebSocket Upgrade 请求中携带 Authorization: Bearer <API_KEY>。 Python 示例 从 MAP_API_KEY 环境变量读取 Key,支持音频和视频输入。

浏览器原生 WebSocket 不能设置 Authorization 请求头,使用 MAP 子协议鉴权:

const ws = new WebSocket(
  "wss://api.modelbest.cn/v1/realtime?mode=audio&model=MiniCPM-o-4.5-Realtime",
  ["map.realtime", "map-api-key.YOUR_API_KEY"],
);
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  if (message.type === "session.queue_done") {
    ws.send(JSON.stringify({
      type: "session.init",
      payload: { config: { generate_audio: true, tts_enabled: true } },
    }));
  } else if (message.type === "response.output.delta" && message.kind === "text") {
    console.log(message.text ?? "");
  }
};

这段代码只展示连接与初始化;收到 session.created 后,按下文发送 input.append 才有用户输入。 浏览器页面的 Origin 还须被 MAP 服务允许;有效 Key 不代表任意站点都已获准连接。 遇到握手 403 时,应检查 Key 与页面 Origin 的授权。浏览器 Key 对页面使用者可见,应使用获准公开的专用 Key。

演示域名与旧入口

新客户端请直接使用上面的 MAP 地址。应用迁移测试站 minicpmo45-test.modelbest.cn 的 /v1/realtime 与旧 /ws/chat、/ws/duplex/{session_id}、/ws/half_duplex/{session_id} 不提供推理:HTTP 返回 410,WebSocket 返回 api_endpoint_moved 后关闭,响应中附有新地址和文档链接。 此行为仅在使用 map_direct_app.py 的应用部署生效;原 minicpmo45.modelbest.cn 需后续正式切换后才生效。 自建 gateway.py 服务继续使用自己的主机地址和原有部署配置,不要求 MAP 的 model 或 Key。

模式

模式端点示例上行输入下行输出说明
Chatwss://api.modelbest.cn/v1/realtime?mode=chat&model=MiniCPM-o-4.5-Realtime一次 turn 的 messages文本增量、可选音频、response.done支持 streaming 和 non-streaming
视频双工wss://api.modelbest.cn/v1/realtime?mode=video&model=MiniCPM-o-4.5-Realtime连续音频,可携带视频帧listen、文本增量、音频增量会话总时长 300 秒
音频双工wss://api.modelbest.cn/v1/realtime?mode=audio&model=MiniCPM-o-4.5-Realtime连续音频listen、文本增量、音频增量会话总时长 600 秒

mode=chat 在 backend runtime 中映射为 turn_based;mode=video 和 mode=audio 都映射为 full_duplex,二者由 Gateway 的请求类型和会话时长限制区分。

三种模式共享同一套事件命名:

  • 初始化使用 session.init
  • 提交输入使用 input.append
  • 输出统一使用 response.output.delta,并通过 kind 区分 listen、text、audio
  • Chat 模式用 response.done 表示一次 turn 输出完成
  • 关闭使用 session.close 和 session.closed

生命周期

Client connects
  <- session.queued / session.queue_update   optional
  <- session.queue_done
  -> session.init
  <- session.created
  -> input.append
  <- response.output.delta / response.done
  -> session.close
  <- session.closed

客户端应等到 session.queue_done 后再发送 session.init。如果没有排队,服务端也会立即发送 session.queue_done。

客户端事件

session.init

session.init 初始化会话。消息必须包含对象类型的 payload 字段。

{
  "type": "session.init",
  "payload": {
    "system_prompt": "你是一个有用的助手"
  }
}

常用字段:

字段模式说明
system_promptvideo / audio双工模式系统提示词
instructionsvideo / audiosystem_prompt 的等价字段
configvideo / audio双工推理配置,例如 length_penalty
voice.ref_audio_base64video / audioLLM 参考音频,base64 PCM
voice.tts_ref_audio_base64video / audioTTS 参考音频,base64 PCM

Chat 模式可以发送空 payload:

{ "type": "session.init", "payload": {} }

input.append

input.append 提交一次模型输入。消息必须包含对象类型的 input 字段。

Chat 模式:

{
  "type": "input.append",
  "input": {
    "messages": [
      { "role": "user", "content": "请只回答:测试" }
    ],
    "streaming": true,
    "generation": {
      "max_new_tokens": 64,
      "length_penalty": 1.1
    },
    "tts": {
      "enabled": false
    }
  }
}

视频/音频双工模式:

{
  "type": "input.append",
  "input": {
    "audio": "<base64 float32 PCM, 16 kHz mono>",
    "video_frames": ["<base64 JPEG>"],
    "force_listen": false,
    "max_slice_nums": 1
  }
}

audio 是双工模式的主要输入。video_frames 只用于 mode=video,mode=audio 不需要携带。

session.close

{
  "type": "session.close",
  "reason": "user_stop"
}

发送后客户端不应再发送新的 input.append。

服务端事件

排队事件

{
  "type": "session.queued",
  "position": 2,
  "estimated_wait_s": 20,
  "ticket_id": "ticket_xxx",
  "queue_length": 3
}

session.queue_update 使用相同字段表达排队位置更新。session.queue_done 表示 worker 已分配完成,可以发送 session.init。

session.created

{
  "type": "session.created",
  "session_id": "sess_xxx",
  "mode": "full_duplex",
  "metrics": {}
}

表示会话初始化完成。

mode 字段表示 backend runtime mode,而不是 URL 中的公开 API mode:mode=chat 通常返回 turn_based,mode=video / mode=audio 通常返回 full_duplex。

response.output.delta

{
  "type": "response.output.delta",
  "kind": "text",
  "session_id": "sess_xxx",
  "response_id": "resp_xxx",
  "input_id": "input_xxx",
  "text": "你好",
  "metrics": {}
}
kind字段说明
listenmetrics模型继续听用户输入
texttext文本增量
audioaudio24 kHz 单声道 float32 PCM,base64 编码

一个 response.output.delta 只表达一种输出分支。文本和音频可能分别到达,客户端应按接收顺序更新字幕和播放音频。

response.done

response.done 只用于 mode=chat,表示一次 turn-based response 完成。

{
  "type": "response.done",
  "session_id": "sess_xxx",
  "response_id": "resp_xxx",
  "text": "测试",
  "reason": "turn_end",
  "metrics": {}
}

session.closed

{
  "type": "session.closed",
  "session_id": "sess_xxx",
  "reason": "user_stop"
}

reason 可能是 user_stop、client_closed、timeout、backend_error 等。客户端收到该事件或 WebSocket 关闭后,应认为会话已经结束。

error

{
  "type": "error",
  "error": {
    "code": "queue_full",
    "message": "Queue full",
    "type": "server_error"
  }
}

协议页面

On this page