Realtime API 使用范例
用于测试 MiniCPM-o Realtime 音频和视频 API 的最小 Python 客户端。
本页提供不依赖浏览器的最小 Python 客户端,用于调用 MiniCPM-o Realtime
API。示例代码位于项目仓库
examples/realtime/
目录。
安装依赖
cd examples/realtime
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt视频示例还需要系统中安装 ffmpeg:
ffmpeg -versionMAP 鉴权
在 MAP 国内控制台 申请自己的 Key,然后设置:
export MAP_API_KEY='YOUR_API_KEY'脚本通过 WebSocket Upgrade 的 Authorization: Bearer 请求头鉴权,不会把 Key 写入结果。
以下命令使用 api.modelbest.cn 和 MiniCPM-o-4.5-Realtime。
海外可改用 api.modelbest.ai 和 海外控制台 申请的对应 Key。
完整 WS(S) URL 的路径和现有参数会保留;--model 可显式指定模型。
自建免鉴权 Gateway 可使用 http://localhost:8006,省略 --model 并取消 MAP_API_KEY;
脚本只对 MAP 公共主机默认添加模型并要求 Key。可用 --api-key-env 指定其他环境变量名。
音频探测
音频探测脚本会连接 wss://api.modelbest.cn/v1/realtime?mode=audio&model=MiniCPM-o-4.5-Realtime,等待
session.queue_done 后发送 session.init,再按 chunk 发送 input.append
事件。音频为 16 kHz 单声道 float32 PCM。
python audio_probe.py \
--url https://api.modelbest.cn \
--model MiniCPM-o-4.5-Realtime \
--input-wav assets/test.wav \
--region local-audio \
--pretty-json仓库内置的 assets/test.wav 很小,适合快速 smoke test。
视频探测
视频探测脚本会用 ffmpeg 从 MP4 中提取 16 kHz 单声道音频和 JPEG 帧,然后发送携带
input.video_frames 的 input.append 事件。
python video_probe.py \
--url https://api.modelbest.cn \
--model MiniCPM-o-4.5-Realtime \
--video /path/to/video.mp4 \
--region local-video \
--pretty-json也可以先下载托管的示例视频:
curl -L -o sample.mp4 \
https://pub-4c730b83fc564d6a85ec9be6da99f10c.r2.dev/minicpmo/realtime-api/examples/VID_20260511_174245.mp4
python video_probe.py \
--url https://api.modelbest.cn \
--model MiniCPM-o-4.5-Realtime \
--video sample.mp4 \
--region local-video \
--pretty-json关键指标
ws_ready_ms:WebSocket 建连耗时。first_text_ms:从连接开始到收到第一个文本增量的耗时。first_audio_ms:从连接开始到收到第一个输出音频 chunk 的耗时。output_audio_chunks:下行音频 chunk 数量。chunk_interarrival_*_ms:下行音频 chunk 到达间隔分布。underrun_count:音频探测脚本模拟播放缓冲时的 underrun 次数。