ドキュメント · ガイド

どのモデルでも画像認識と画像生成

DeepSeek や GLM など、画像を読めないモデルは多くあります。Claude Code や Codex にスクリーンショットを貼ってからそうしたモデルに切り替えると、たいていリクエストが断られます。magpie を通すと、画像を読めるモデルがまず画像を説明し、その説明を画像の位置に入れて渡します。今のターン、前のターン、ツールの結果の画像も同じです。どのモデルに切り替えてもスクリーンショットはそのまま使えます。逆に、エージェントは Magpie Image ツールで画像や動画を生成することもできます。

画像認識

画像を説明するモデルは設定 › モデル › 画像認識で選びます。

自動：既定値です。設定済みの、画像を読めるモデルから magpie が選びます。枠が残っているものが優先です。
モデルを選ぶ：常にそのモデルを使います。そのプロバイダーが削除またはオフになると、この行にそう表示され、自動の選択が代わりに使われます。
オフ：画像を説明しません。画像を読めないモデルは、最新のメッセージに画像があるリクエストを断ります。

各画像の説明は一度だけで、キャッシュされます。エージェントが毎ターン同じ画像を送り直しても、料金は二重にかかりません。1 つのリクエストの画像は同時に説明され、並列は最大 4 枚です。モデルの横で思考の強さを選べます。選ばない場合はそのモデルの最も低い段階です。

画像を読めるモデルには、説明ではなく画像そのものが渡ります。

画像認識 MCP サーバー

画像認識は MCP サーバー（Streamable HTTP）としても使えます。ツールは analyze_image の 1 つで、画像認識モデルで画像を読みます。アドレスは画像認識 MCP サーバーの行にあり、既定では次のとおりです。

ターミナル

http://127.0.0.1:3425/mcp/magpie/vision

アドレスを MCP サーバーとしてエージェントに追加Cursor、Claude Desktop など、Streamable HTTP に対応したエージェントならどれでも使えます。
analyze_image を呼ぶimage には http(s) URL、data URL、またはこのコンピューターのファイルの絶対パス（~/ と file:// も可、最大 20 MB）を渡します。省略できる prompt で画像について質問でき、なければ画像を説明します。

ファイルのパスはこのコンピューターからの呼び出しでのみ使えます。別のコンピューターから使うとき（magpie をローカルネットワークで共有中）は、Authorization: Bearer <key> でゲートウェイキーを送り、画像は URL か data URL で渡します。画像認識がオフ、または画像を読めるモデルがない場合、ツールはどこで選ぶかを示すエラーを返します。

画像と動画の生成

Magpie Image は magpie 自身の MCP ツール（magpie mcp image、stdio）です。ライブラリからエージェントに追加するか、設定 › モデル › 画像生成のエージェントに Magpie Image を付与… を使います。ツールは 3 つです。

generate_image：プロンプトから画像を生成するか、reference_images を編集・合成します。size（1024x1024 や 16:9 など）、n（1〜4 枚）、quality、background を指定できます。
generate_video：プロンプトから 1〜15 秒の短い動画を生成します。最初のフレームにする画像や参考画像も渡せます。
generation_result：まだ作成中の画像や動画を、返された id で待ち、保存先を返します。

path を指定しなければ、画像はプロジェクトの generated-images フォルダー、動画は generated-videos に保存され、既存のファイルは上書きされません。画像は画像生成で選んだモデル（自動なら magpie が選ぶ）で、動画は magpie が見つけた最初の動画モデルで作られます。

多くのエージェントはツール呼び出しを 30〜60 秒しか待ちませんが、画像生成には 1 分以上かかることがよくあります。そのため 1 回の呼び出しは最大 20 秒だけ待ち、終わっていなければ id を返します。ジョブはその後も続き、できたものを保存します。

画像 API

ゲートウェイ自体も OpenAI 形式の画像エンドポイントを提供し、選んだモデルの画像 API に変換します。

ターミナル

/v1/images/generations
/v1/images/edits

OpenRouter や Volcengine Ark など、プロバイダーごとのエンドポイントの違いは magpie が吸収します。ChatGPT アカウントの GPT Image、Grok サブスクリプションの Grok Imagine、WorkBuddy プランの画像モデルは、アカウント側のモデル一覧で制限されません。ルーティンググループを指す名前なら、グループの順にメンバーを試し、失敗すると次に移ります。

画像生成のタイムアウト

設定 › モデル › 画像生成のタイムアウト：プロバイダーが画像を描いて返すまでの時間です。1〜60 分、既定は 5 分。遅い画像エンドポイントでは長くしてください。

よくある質問

DeepSeek は画像を読めますか？

DeepSeek のモデル自体は画像を読めません。magpie を通すと、画像認識モデルがまず画像を説明し、その説明が画像の代わりに DeepSeek に渡るので、Claude Code のスクリーンショットもそのまま使えます。

画像認識に追加の料金はかかりますか？

画像の説明には画像認識モデルの枠または料金を使います。各画像の説明は一度だけで、結果はキャッシュされます。

Claude Code に画像を生成させるには？

ライブラリから Claude Code に Magpie Image を追加します。generate_image ツールが使えるようになり、設定 › モデル › 画像生成のモデルで描いて、プロジェクトの generated-images フォルダーに保存します。

Cursor で magpie の画像認識を使えますか？

使えます。/mcp/magpie/vision を MCP サーバー（Streamable HTTP）として Cursor に追加すると、analyze_image ツールが使えます。

関連ページ：どのモデルでもウェブ検索、DeepSeek を Claude Code・Codex・Gemini CLI・OpenCode で使う。エラーが出たらよくあるエラーの直し方：401・429・502・504 などを見るか、Discord で質問してください。