Kimi K3 视觉多模态教程:图片、视频输入与看图写代码

Kimi K3 最实用的升级之一,是把视觉做成了原生能力 —— 不用外挂 OCR 或另调一个视觉模型,直接把图片、视频丢进 messages,让它「看着图」写代码、读图表、理解界面。但多模态请求的构造有几个必须踩对的细节,踩错就直接报错。这篇把正确姿势讲清楚。

两条铁律先记住

K3 的视觉输入有两个硬性要求,先记牢:

1. 图文内容必须是「对象数组」,不能拼成一个序列化后的字符串。也就是 content 要写成 [{type:"text",...}, {type:"image_url",...}] 这种列表。
2. 不支持公网图片 URL。本地图片用 base64 内联,视频用 files API 上传后以 ms://<file-id> 引用。直接传 https://example.com/a.png 会失败。

记住这两条,大部分「视觉请求报错」就避开了。

图片输入:base64 内联

import base64, os
from openai import OpenAI

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

with open("design.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有哪些 UI 组件?列个清单。"},
            {"type": "image_url",
             "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
)
print(resp.choices[0].message.content)

注意 image_url.url 用的是 data URI(data:image/png;base64,...),这是「内联 base64」而不是「公网链接」,K3 支持的正是这种。

视频输入:files API + ms:// 引用

视频文件先通过 files API 上传,拿到 file id 后用 ms://<file-id> 在消息里引用:

# 1) 上传视频,拿到 file id
f = client.files.create(file=open("demo.mp4", "rb"), purpose="assistants")

# 2) 在消息里用 ms://<file-id> 引用
resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这段操作录屏里,用户完成了哪几步?"},
            {"type": "image_url", "image_url": {"url": f"ms://{f.id}"}},
        ],
    }],
)

上传接口的 purpose 等参数以官方文档为准,接入前建议核对当前版本。

实战:看设计稿生成前端

K3 主打「结合软件工程和视觉分析」的场景,最典型的就是照着设计稿写前端:

with open("mockup.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text":
                "严格照这张设计稿写出对应的 HTML + Tailwind CSS,"
                "布局、间距、配色尽量还原,输出完整可运行的单文件。"},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
)
print(resp.choices[0].message.content)

同样的思路可以用在:读图表数据做分析、看报错截图定位问题、按游戏 / CAD 截图改代码。因为 K3 有 1M 上下文,你还能把「设计稿 + 现有代码库」一起塞进去,让它在完整工程语境里改,而不是凭空生成(长上下文用法见 1M 上下文指南)。

常见报错

• 视觉请求直接失败:多半是传了公网 URL,或把 content 拼成了字符串。改成 base64 / ms:// + 对象数组。
• 图太大 / 超预算:图片和视频都算 token,大图或长视频会吃掉大量上下文,必要时压缩尺寸、抽帧。
• 多轮丢状态:带图的多轮对话,记得把完整 assistant message 原样回传,别只留 content。

小结

K3 的原生视觉让「看图 + 写代码」成了单模型单请求就能做的事,记住两条铁律(对象数组、不吃公网 URL)基本就不会翻车。完整接入、定价和迁移见 Kimi K3 API 接入教程。想用一个 Key 同时调 K3 和其它多模态模型、按任务比效果,从 GetModel 控制台拿个 Key 开始。