Kimi K3.1 Pro 图片与视频输入配置：Base64、文件 ID 与多模态消息结构

一句话结论

Kimi K3.1 Pro 的视觉请求把用户消息的 content 写成 JSON 数组；图片可用 Base64 image_url，视频应先上传后用 ms://<file-id> 的 video_url 引用。

适用场景

• 适合的任务：在 Kimi API Chat Completions 中配置图片理解、视频理解和多图片消息。

• 不适合的任务：把公网图片 URL 直接传给模型、把 SVG 当作图片上传，或据此推断未公开的文件大小和视频时长上限。

• 适用的模型版本：kimi-k3.1-pro；官方页面同时列出 kimi-k3、kimi-k2.6、kimi-k2.7-code 和 kimi-k2.7-code-highspeed，并说明这些模型可理解视频。

• 适用的客户端、Agent 或 API：Kimi API 的 Chat Completions；官方示例使用 Python OpenAI SDK 和 https://api.moonshot.ai/v1。

• 推荐的推理档位和参数：本稿不新增推理配置；官方建议参数使用模型默认值，不手动设置 temperature、top_p、n，除非已核对对应模型约束。

可直接使用的内容

图片：本地文件转 Base64

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

image_path = "kimi.png"
with open(image_path, "rb") as f:
    image_data = f.read()
image_url = (
    f"data:image/{os.path.splitext(image_path)[1].lstrip('.')};base64,"
    f"{base64.b64encode(image_data).decode('utf-8')}"
)

completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": image_url}},
            {"type": "text", "text": "请描述这张图片。"},
        ],
    }],
)
print(completion.choices[0].message.content)

关键结构是：

{
  "type": "image_url",
  "image_url": {"url": "data:image/png;base64,<base64-data>"}
}

视频不能使用上述图片 Base64 结构。官方示例先用 purpose="video" 上传，再在消息中使用：

{
  "type": "video_url",
  "video_url": {"url": "ms://<file-id>"}
}

图片或视频后可在同一个 content 数组中加入 type: "text" 的任务说明。content 必须是数组对象，不能把这个数组序列化成字符串。

测试或工作流步骤

1. 确认请求使用 model: "kimi-k3.1-pro" 和 Chat Completions。

2. 图片读取为二进制并编码成 data:image/<扩展名>;base64,<数据>。

3. 将图片和文字说明作为同一用户消息 content 数组中的独立对象。

4. 视频先通过 Files API 上传，示例的 purpose 为 video。

5. 将上传返回的文件 ID 组装为 ms://<file-id>，放入 video_url.url。

6. 输入较大或需要多次引用时优先使用文件上传；很大的视频必须使用文件上传，因为请求体有整体大小限制。

7. 视觉请求发送前可调用 estimate tokens API 估算图片或视频 token 消耗。

原始证据与数据

• 官方页面明确把 kimi-k3.1-pro 列入 Kimi Vision Model，并说明该模型可理解图片和视频。

• 图片支持的 MIME 类型：image/jpeg、image/png、image/gif、image/webp、image/bmp、image/heic、image/heif。

• 动态 GIF 和 WebP 也通过 image_url 传入，但底层系统可能按视频解码，token 消耗按视频计算。

• SVG 不支持作为图片输入；上传 SVG 或通过 image_url（包括 Base64）传入会被拒绝。需要理解 SVG 时，应把 SVG XML 源码作为文本放进消息。

• 视频支持的 MIME 类型：video/mp4、video/mpeg、video/mov、video/avi、video/x-flv、video/mpg、video/webm、video/wmv、video/3gpp。

• 官方建议图片分辨率不超过 4K（4096×2160），视频分辨率不超过 FHD（1920×1080）；更高分辨率只会增加处理时间，不会提升理解表现。

• Vision 模型没有图片数量限制，但单次请求体不得超过 100M。页面没有给出单张图片、单个文件或视频时长的独立数值上限。

• URL 格式图片不支持；当前支持 Base64 图片内容，以及通过文件 ID 引用的图片或视频。

• 页面列出支持多轮对话、流式输出、工具调用、JSON Mode 和 Partial Mode。

• 图片和视频按动态 token 计算；分辨率越高通常消耗越多 token，视频还取决于关键帧数量和分辨率。

• 本文没有使用 API Key 发起本地请求，不包含本地成功率、延迟、返回内容或兼容性实测。

适用边界

• 100M 是官方给出的单次请求体上限，不等于每张图片或每个视频文件都可占用 100M。

• “图片数量没有限制”仍受请求体大小限制约束；页面没有给出一个请求可放入的固定张数。

• 4K 和 FHD 是官方建议分辨率，不是页面声明的硬性拒绝阈值。

• 页面没有为视频给出时长、帧率、文件大小或关键帧数量的固定上限，本文不补充这些数值。

• 官方示例使用 ms:// 文件引用；不要把它改写成公网 URL，也不要把视频对象伪装成 image_url。

复现说明

1. 打开官方 Configure Kimi Vision Models，确认页面正文和规范化 URL。

2. 用无敏感图片运行上方 Python 示例；运行前设置 MOONSHOT_API_KEY，并准备本地 kimi.png。

3. 对照请求体检查 messages[0].content 的类型是数组，数组元素分别是 image_url 和 text 对象。

4. 若验证视频，使用 Files API 上传文件并记录返回的 file ID，再构造 ms://<file-id> 的 video_url。

5. 本次采集只完成官方文档核验；没有提交真实 API 请求，因此没有本地 API 测试结果。