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。
模式
| 模式 | 端点示例 | 上行输入 | 下行输出 | 说明 |
|---|---|---|---|---|
| Chat | wss://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_prompt | video / audio | 双工模式系统提示词 |
instructions | video / audio | system_prompt 的等价字段 |
config | video / audio | 双工推理配置,例如 length_penalty |
voice.ref_audio_base64 | video / audio | LLM 参考音频,base64 PCM |
voice.tts_ref_audio_base64 | video / audio | TTS 参考音频,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 | 字段 | 说明 |
|---|---|---|
listen | metrics | 模型继续听用户输入 |
text | text | 文本增量 |
audio | audio | 24 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"
}
}