MiniCPM-V 与 MiniCPM-o 4.5/4.6 Chat Completions API 接入指南：文本、图像与视频理解

MiniCPM-V 与 MiniCPM-o 4.5/4.6 Chat Completions API 接入指南：文本、图像与视频理解

【免费下载链接】MiniCPM-VA Pocket-Sized MLLM for Ultra-Efficient Image and Video Understanding on Your Phone项目地址: https://gitcode.com/GitHub_Trending/mi/MiniCPM-V

本篇指南围绕 MiniCPM-V 4.5 / 4.6 与 MiniCPM-o 4.5 的在线 Chat Completions API（docs/api.md）展开，完整讲解接口地址、鉴权方式、可用模型 ID，以及通过curl与 Python 发起纯文本、图像（base64 data URL）与视频理解请求的实操方法。读完本文，你可以直接使用公开测试 Key 在几分钟内完成多模态模型调用，并能将同一套请求格式平滑迁移到本地transformers serve提供的 OpenAI 兼容服务上。

API 概览：端点、鉴权与模型 ID

MiniCPM-V 4.5 / 4.6 与 MiniCPM-o 4.5 均通过标准 Chat Completions 接口对外提供服务，与 OpenAI 生态的调用习惯保持一致。接口三要素如下：

Base URL: https://api.modelbest.cn/v1 Chat API: POST /chat/completions Authorization: Bearer <API_KEY> Content-Type: application/json

其中鉴权通过请求头Authorization: Bearer <API_KEY>完成。官方目前提供了一个免费公开测试 Key，可直接用于体验服务：

sk-live-kmwPsO1yz9kJfbp8c6az72I-BjfZBX-5V5CmI9yTsXw

提示：该 Key 为公开测试用途，生产环境请替换为自己的专属 API Key，并关注服务方的限流与配额策略。

当前接口可用的模型 ID 共四个，覆盖轻量、推理增强、高精度与全模态四个方向：

从仓库 README.md 的介绍可以确认这些模型的架构背景：MiniCPM-V 4.6 基于 SigLIP2-400M 与 Qwen3.5-0.8B 构建，引入混合 4x/16x 视觉 token 压缩以降低视觉编码开销；MiniCPM-V 4.5 基于 Qwen3-8B 与 SigLIP2-400M；MiniCPM-o 4.5 则在 Qwen3-8B 之上端到端集成了视觉、语音与全双工流式能力。

MiniCPM-V 4.6：从纯文本到多模态请求

MiniCPM-V 4.6 可通过 Chat Completions API 发起纯文本、图像与视频三类请求，下面逐一给出可直接复制的示例。

纯文本请求

最简单的调用只需在messages中传一个user角色的文本消息：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-V-4.6-1B", "messages": [ { "role": "user", "content": "Introduce yourself in one sentence." } ] }'

切换到 Thinking 模型

若希望模型先进行逐步推理再给出答案，只需把model字段替换为：

"MiniCPM-V-4.6-Thinking"

需要特别注意的是，Thinking 模型的中间推理过程会通过message.reasoning字段单独返回，与最终答案message.content分离，方便你在应用层分别处理或仅展示最终结果。

图像理解：base64 data URL

图像通过image_url内容类型传递，图片本身以base64 data URL形式嵌入请求体：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-V-4.6-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,<BASE64_IMAGE>" } } ] } ] }'

本地文件转 base64 可用一行命令完成（注意编码后体积会比原始文件膨胀约 1/3，大图请评估请求体大小）：

python -c "import base64,sys;print(base64.b64encode(open(sys.argv[1],'rb').read()).decode())" your_image.png

视频理解：video_url data URL

视频与图像的传递方式一致，只是内容类型换为video_url，例如data:video/mp4;base64,...：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-V-4.6-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this video briefly." }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64,<BASE64_VIDEO>" } } ] } ] }'

官方文档特别说明：video_url格式对全部四个模型 ID 通用——即MiniCPM-V-4.5-9B、MiniCPM-V-4.6-1B、MiniCPM-V-4.6-Thinking、MiniCPM-O-4.5-9B均可使用同一套视频请求体，仅需替换model字段。

Python 示例（标准库实现）

不依赖任何第三方 SDK，仅用 Python 标准库urllib即可完成调用：

import json import urllib.request api_key = "<API_KEY>" payload = { "model": "MiniCPM-V-4.6-1B", "messages": [ { "role": "user", "content": "List three use cases for MiniCPM-V.", } ], } request = urllib.request.Request( "https://api.modelbest.cn/v1/chat/completions", data=json.dumps(payload).encode("utf-8"), headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, method="POST", ) with urllib.request.urlopen(request) as response: data = json.loads(response.read().decode("utf-8")) print(data["choices"][0]["message"]["content"])

响应解析要点：顶层结构为{"choices": [{"message": {...}}]}，最终回答位于data["choices"][0]["message"]["content"]；若使用 Thinking 模型，推理内容位于data["choices"][0]["message"]["reasoning"]。Python 中请求多模态输入时，只需把payload["messages"][0]["content"]替换为与 curl 示例相同的多模态数组（{"type": "text"}/{"type": "image_url"}/{"type": "video_url"}）即可。

MiniCPM-V 4.5：同一接口，更高精度

MiniCPM-V 4.5 使用与上文完全相同的 Chat Completions API（文本 / 图像 / 视频），唯一的区别是把模型 ID 换成MiniCPM-V-4.5-9B。其视觉语言能力定位更强（docs/minicpm_v4dot5_en.md 中介绍了基于 LLaVA-UHD 的高分辨率图像处理与统一 3D-Resampler 视频压缩），适合对精度要求更高的图像理解、文档解析等场景：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-V-4.5-9B", "messages": [ { "role": "user", "content": "Introduce yourself in one sentence." } ] }'

图像与视频请求体可参照上一节，将image_url/video_url的 data URL 照搬即可。

MiniCPM-o 4.5：全模态理解与实时交互

MiniCPM-o 4.5 通过 Chat Completions API 支持三类离线理解请求（文本、图像、视频），同时还支持全双工（full-duplex）实时多模态交互。

文本 / 图像 / 视频请求

将模型 ID 换为MiniCPM-O-4.5-9B，即可复用同一套请求结构：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-O-4.5-9B", "messages": [ { "role": "user", "content": "Introduce yourself in one sentence." } ] }'

图像理解请求（image_url传 base64 data URL）：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-O-4.5-9B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this image." }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,<BASE64_IMAGE>" } } ] } ] }'

视频理解请求（video_url传 base64 data URL）：

curl https://api.modelbest.cn/v1/chat/completions \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniCPM-O-4.5-9B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Describe this video briefly." }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64,<BASE64_VIDEO>" } } ] } ] }'

Realtime API：全双工实时交互

除了上述离线请求外，MiniCPM-o 4.5 还提供全双工实时多模态交互能力——输入的视频与音频流、输出的语音与文本流互不阻塞，模型可以"边看边听边说"。完整的 Realtime API 接入文档见 MiniCPM-o 4.5 官方在线文档中的 Realtime API Overview（docs/api.md 末尾给出了对应链接）。

仓库层面同样有对应佐证：MiniCPM-o 2.6 的 model_server.py 展示了基于 FastAPI + WebSocket 的流式服务实现，可作为理解全双工交互服务形态的参考。

实战要点与仓库交叉验证

请求体格式规范

• messages数组中的每个元素包含role（如user）与content；纯文本时content为字符串，多模态时content为对象数组。
• 多模态数组中，文本项为{"type": "text", "text": "..."}，图像项为{"type": "image_url", "image_url": {"url": "data:image/...;base64,..."}}，视频项为{"type": "video_url", "video_url": {"url": "data:video/...;base64,..."}}。
• data URL 的 MIME 类型需与文件实际格式匹配（如image/png、image/jpeg、video/mp4）。

与本地 OpenAI 兼容服务的对照

这套image_url/video_url格式并非在线服务独有。仓库 README.md 展示了通过 Hugging Face Transformers 的transformers serve在本地启动 OpenAI 兼容服务器：

pip install "transformers[serving]>=5.7.0" transformers serve openbmb/MiniCPM-V-4.6 --port 8000 --host 0.0.0.0 --continuous-batching

随后即可用与在线 API 几乎相同的请求体访问本地服务：

curl -s http://localhost:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "openbmb/MiniCPM-V-4.6", "messages": [{ "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "https://huggingface.co/datasets/openbmb/DemoCase/resolve/main/refract.png"}}, {"type": "text", "text": "What causes this phenomenon?"} ] }] }'

这意味着：先用在线 API 完成功能验证，再切换到本地自托管服务的开发路径非常平滑，messages结构可以几乎原样复用。

评测框架中的消息格式佐证

仓库的评测套件 eval_mm/vlmevalkit 中，本地推理封装 minicpm_v.py 采用[{'role': 'user', 'content': ...}]的对话结构组织输入，并支持text/image类型的消息项——与 API 的messages多模态数组设计一脉相承，可帮你理解该系列模型统一的对话式输入约定。

模型选型建议

注意事项

• 鉴权失败：请检查Authorization: Bearer <API_KEY>头与API_KEY变量是否正确设置；若使用公开测试 Key，请注意其为共享 Key，存在被限流或调整的可能。
• 请求体积：base64 编码会使 payload 体积增大（约 33%），超长视频建议先剪辑或抽帧后再提交。
• 视频兼容性：video_url格式适用于全部四个模型 ID，但不同模型对视频帧数、分辨率与时长的处理能力不同（如 MiniCPM-V 4.5 支持更高 FPS 视频理解），实际效果以服务端返回为准。
• Thinking 输出：使用MiniCPM-V-4.6-Thinking时，推理过程与最终答案分字段返回，展示层需要自行决定是否呈现推理内容。

通过以上示例与要点，你已经可以完整覆盖"文本问答、图像理解、视频理解、推理增强、实时交互"五类调用场景，并具备将同一套 API 格式落地到本地 OpenAI 兼容服务的迁移能力。

【免费下载链接】MiniCPM-VA Pocket-Sized MLLM for Ultra-Efficient Image and Video Understanding on Your Phone项目地址: https://gitcode.com/GitHub_Trending/mi/MiniCPM-V