Realtime API Examples
Minimal Python clients for testing MiniCPM-o Realtime audio and video APIs.
This page shows minimal Python clients for calling the MiniCPM-o Realtime API
without a browser. The examples live in the repository under
examples/realtime/.
Install
cd examples/realtime
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txtFor the video example, make sure ffmpeg is available:
ffmpeg -versionMAP authentication
Obtain your own key from the MAP platform and set:
export MAP_API_KEY='YOUR_API_KEY'The scripts send Authorization: Bearer during the WebSocket Upgrade and do not include the key in results.
The commands below use api.modelbest.ai and MiniCPM-o-4.5-Realtime.
For mainland China, use api.modelbest.cn with a key from the China platform.
Full WS(S) URLs retain their paths and existing query parameters; --model explicitly selects a model.
For a self-hosted unauthenticated Gateway, use a host such as http://localhost:8006,
omit --model, and unset MAP_API_KEY. Only the public MAP hosts get a default model and require a key.
Use --api-key-env to read credentials from a differently named environment variable.
Audio probe
The audio probe opens wss://api.modelbest.ai/v1/realtime?mode=audio&model=MiniCPM-o-4.5-Realtime, waits for
session.queue_done, sends session.init, and then sends audio chunks as
input.append events. Input audio is 16 kHz mono float32 PCM.
python audio_probe.py \
--url https://api.modelbest.ai \
--model MiniCPM-o-4.5-Realtime \
--input-wav assets/test.wav \
--region local-audio \
--pretty-jsonThe bundled assets/test.wav is intentionally small and suitable for a quick
smoke test.
Video probe
The video probe extracts 16 kHz mono audio and JPEG frames from an MP4 file with
ffmpeg, then sends input.append events with input.video_frames.
python video_probe.py \
--url https://api.modelbest.ai \
--model MiniCPM-o-4.5-Realtime \
--video /path/to/video.mp4 \
--region local-video \
--pretty-jsonYou can also download the hosted sample video first:
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.ai \
--model MiniCPM-o-4.5-Realtime \
--video sample.mp4 \
--region local-video \
--pretty-jsonWhat to look at
ws_ready_ms: WebSocket connection time.first_text_ms: time from connection start to the first text delta.first_audio_ms: time from connection start to the first output audio chunk.output_audio_chunks: number of downstream audio chunks.chunk_interarrival_*_ms: output audio chunk arrival interval distribution.underrun_count: simulated playback buffer underruns in the audio probe.