Kimi K3 ビジョン・マルチモーダル入門:画像・動画入力と画面からコード生成

Kimi K3 で最も実用的な進化のひとつが、ビジョンをネイティブ機能にしたことです。OCR を外付けしたり別のビジョンモデルを呼んだりせず、画像や動画をそのまま messages に入れて、モデルに「図を見ながら」コードを書かせ、グラフを読ませ、画面を理解させられます。ただしマルチモーダルリクエストの組み方にはいくつか外せない要点があり、間違えるとそのままエラーになります。この記事で正しいやり方を整理します。

まず 2 つの鉄則

K3 のビジョン入力には 2 つの厳格な要件があります。何よりも先に頭に入れてください。

1. 画像とテキストの内容は「オブジェクト配列」でなければならない。シリアライズした文字列にまとめてはいけません。つまり content は [{type:"text",...}, {type:"image_url",...}] のようなリストにします。
2. 公開画像 URL は非対応。ローカル画像は base64 でインライン化し、動画は files API でアップロードしてから ms://<file-id> で参照します。https://example.com/a.png をそのまま渡すと失敗します。

この 2 つを押さえておけば、「ビジョンリクエストのエラー」の大半は避けられます。

画像入力: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:// とオブジェクト配列に直しましょう。
• 画像が大きすぎる / 予算オーバー:画像も動画もトークンとして計上され、大きな画像や長い動画は大量のコンテキストを消費します。必要に応じてサイズを圧縮したりフレームを抽出したりしてください。
• 複数ターンで状態が失われる:画像付きの複数ターン対話では、完全な assistant メッセージをそのまま送り返すのを忘れずに。content だけを残してはいけません。

まとめ

K3 のネイティブビジョンにより、「図を見る+コードを書く」が単一モデル・単一リクエストでこなせるようになりました。2 つの鉄則(オブジェクト配列、公開 URL 非対応)を覚えておけば、基本的につまずきません。導入全体・価格・移行については Kimi K3 API 入門 を参照してください。1 つの Key で K3 と他のマルチモーダルモデルを同時に呼び、タスクごとに効果を比べたいなら、GetModel コンソールで Key を取得して始めましょう。