generate-image

画像の生成

OpenRouter の Image API を通じて画像を生成・編集します。この API では、1 種類のリクエスト形式で Gemini、Seedream、Recraft、 GPT-Image、Riverflow、その他約 30 のモデルを利用できます。

使用する場面

このスキルを使用する対象： 写真やフォトリアルな画像、イラストやアート作品、コンセプトアート、 プレゼンテーションやポスター用のビジュアル、ロゴやベクターマーク、画像編集、参考画像からの 合成です。

次の用途には scientific-schematics を使用してください： フローチャート、回路図、生物学的経路、 システムアーキテクチャ図、CONSORT 図、その他の技術的な模式図です。

API キー

生成には OpenRouter のキーが必要です。スクリプトは次の順序でキーを探します。

1. --api-key
2. OPENROUTER_API_KEY 環境変数
3. .env ファイル内の OPENROUTER_API_KEY=。作業ディレクトリから親ディレクトリを順に検索した後、 スクリプト自身のディレクトリを検索します

いずれも見つからない場合、スクリプトはセットアップ手順を表示して終了します。キーはこちらです：https://openrouter.ai/keys

--list-models、--model-info、--dry-run の実行にキーは不要です。

クイックスタート

# Generate
python scripts/generate_image.py "A beautiful sunset over mountains"

# Edit an existing image
python scripts/generate_image.py "Make the sky purple" -i photo.jpg -o edited.png

パスはこのスキルのディレクトリからの相対パスです。出力先の既定値は generated_image.<ext> で、拡張子はモデルが返したメディアタイプに応じて決まります。実行後、リクエストごとのコストが表示されます。

生成後は画像を確認してください。 画像を読み戻して、どこかで使用する前に確認してください。構図、アスペクト比、テキストはいずれも、モデルが気付かれないまま間違えることがあります。

モデルの選択

既定値：google/gemini-3.1-flash-image

用途	モデル
全般的な品質、プロンプトへの忠実度	google/gemini-3.1-flash-image
Gemini の最上位モデル	google/gemini-3-pro-image
低コストでの反復	google/gemini-3.1-flash-lite-image（1K のみ）、openai/gpt-image-1-mini
フォトリアルな表現の制御、再現可能なシード	bytedance-seed/seedream-4.5
1 回のリクエストで複数画像を生成	bytedance-seed/seedream-4.5、openai/gpt-image-2（最大 10 枚）
ベクター／SVG 出力	recraft/recraft-v4.1-vector
透明な背景	openai/gpt-image-1 と --background transparent
画像内の読みやすいテキスト	recraft/recraft-v4.1、sourceful/riverflow-v2.5-pro — 下記の注意事項を参照してください

references/models.md には、モデルごとのパラメーター、許可される値、価格を含む全カタログがあります。最新の一覧が正確な情報源であり、無料で利用できます。

python scripts/generate_image.py --list-models            # every model and its allowed values
python scripts/generate_image.py --list-models gemini     # filtered by substring
python scripts/generate_image.py --model-info openai/gpt-image-1   # one model, plus pricing

パラメーターのサポート状況はモデルによって異なります

ここが最も重要な点です。モデルによってサポートするパラメーターセットと許可される値が異なり、モデルがサポートしていないものを送ると無視されるのではなく、拒否されます。

このスクリプトは、実行前にライブカタログとリクエストを照合するため、不正なパラメーターはローカルで1秒もかからずに失敗し、使用可能な値が表示されます。

$ python scripts/generate_image.py "abstract pattern" -m openai/gpt-image-2 --background transparent
Error: Request rejected before billing (1 problem):
  - background=transparent is not allowed; this model accepts: auto, opaque

大まかな目安です。ただし、カタログは更新されるため、確認結果を優先してください。

• --resolution — Gemini、Seedream、Riverflow、Krea、Grok。対応する解像度は異なります。512 は Gemini 3.1 Flash のみ、4K は Gemini 3 Pro／Seedream／Riverflow、1K は gemini-3.1-flash-lite-image と Krea モデルのみです。
• --output-format — Riverflow 2.5 のみ（png、jpeg、webp。fast バリアントは jpeg のみ）。Gemini、OpenAI、Seedream、Recraft は、それぞれ独自のコンテナー形式を選択します。
• --quality、--background、--output-compression — OpenAI ファミリーが対応し、Riverflow 2.5 は --background にも対応します。--background transparent は gpt-image-2 と gpt-5.4-image-2 では利用できません。gpt-image-1、gpt-image-1-mini、gpt-5-image、または gpt-5-image-mini を使用してください。
• --seed — Seedream と Krea に対応します。Gemini と OpenAI は対応していません。
• --aspect-ratio — ほぼすべてのモデルが対応しますが、選択肢は大きく異なります。gpt-image-1 が受け付けるのは 1:1、3:2、2:3、auto のみで、gpt-5-image* は一切受け付けません。
• --n — モデルごとに上限があります。Gemini、Riverflow、MAI、Grok は1、Recraft は6、Seedream と OpenAI は10です。Krea モデルはこのパラメーターを拒否します。

生成や課金をせずに検証し、正確なリクエストボディを表示するには、--dry-run を指定してください。API 自身に判定させたい場合は、--no-preflight を指定して事前チェックをスキップします。

プロンプトの作成

出力品質を左右するのは、モデルの選択よりもプロンプトの品質です。次の内容を、それぞれ1文で指定します。

1. 被写体 — フレームに何が、どの程度写っているか。「96ウェルプレートの上にある、1本のピペットチップ。」
2. 媒体とスタイル — 写真、水彩画、3Dレンダリング、フラットなベクター画像、科学イラスト。
3. 照明と配色 — 「柔らかな拡散光、青と白を基調とした配色。」
4. 構図 — 「広角ショット、被写体は中央より左、タイトル用の余白を右側に確保。」
5. 避けるもの — 「テキスト、ラベル、透かしは入れない。」

ポスターやスライドでは、キャプションやタイトルを置くための余白を指定することが、構図に関する指示の中で最も役立ちます。

低コストで試行を重ねましょう。まず gemini-3.1-flash-lite-image で下書きを作成し、決めた文面を使って、実際に使いたいモデルで再生成します。最初からやり直すのではなく調整するには、最後の出力を参照画像として渡し（-i out.png）、変更点だけを説明します。

編集と参照画像

-i/--input は繰り返し指定でき、ローカルパス、HTTP(S) URL、データ URL を受け付けます。ローカルファイルは base64 にエンコードされ、input_references として送信されます。

# Single-image edit
python scripts/generate_image.py "Add sunglasses to the person" -i portrait.png

# Composite several references
python scripts/generate_image.py "Blend these two styles" -i style_a.png -i style_b.jpg -o blend.png

# Reference an image already on the web
python scripts/generate_image.py "Restyle as a watercolor" -i https://example.com/photo.jpg

参照画像の上限はモデルによって異なります。OpenAI は16枚、Gemini と Seedream は14枚、riverflow-v2*-pro は10枚、gemini-2.5-flash-image と Grok は3枚、Recraft、MAI、Krea は1枚です。ローカルで受け付ける形式は PNG、JPEG、GIF、WebP です。Riverflow v2 では、出力料金に加えて参照画像1枚につき $0.20 が課金されます。

使用例

-o のパスはスクリプトが作成する出力先であり、スキルに同梱されているファイルではありません。

# Wide hero image for a poster, with space reserved for the title
python scripts/generate_image.py \
  "Laboratory with modern equipment, photorealistic, well-lit, wide shot, \
   equipment on the left, empty wall on the right, no text" \
  --aspect-ratio 21:9 --resolution 2K -o poster/hero.png

# Conceptual illustration for a manuscript — illustrative, never presented as data
python scripts/generate_image.py \
  "Stylised illustration of immune cells surrounding a tumour cell, scientific illustration, \
   cool palette, no text" \
  --resolution 2K -o figures/immunotherapy_concept.png

# Vector logo
python scripts/generate_image.py \
  "Minimal geometric fox logo, two colors" \
  -m recraft/recraft-v4.1-vector -o assets/logo.svg

# Slide background with a transparent alpha channel
python scripts/generate_image.py \
  "Abstract molecular pattern, subtle, blue and white, no text" \
  -m openai/gpt-image-1 --background transparent -o slides/bg.png

# Four variations in one request
python scripts/generate_image.py \
  "Stylized neuron network illustration" \
  -m bytedance-seed/seedream-4.5 --n 4 -o variations.png
# -> variations_1.png ... variations_4.png

# Reproducible output
python scripts/generate_image.py "A cat astronaut" \
  -m bytedance-seed/seedream-4.5 --seed 42

# Check a request costs nothing to get wrong
python scripts/generate_image.py "A cat astronaut" --resolution 4K --dry-run

スクリプトのパラメーター

フラグ	用途
prompt	画像の説明、または適用する編集内容（--list-models／--model-info を指定しない場合は必須）
-m, --model	モデルのスラッグ（デフォルトは google/gemini-3.1-flash-image）
-o, --output	出力パス。拡張子は返されたメディアタイプをデフォルトで使用します
-i, --input	参照画像。パス、URL、またはデータ URL。複数指定可能
--n	リクエストごとの画像数。モデルの上限が適用されます
--aspect-ratio	1:1、16:9、9:16、4:3、3:2、21:9、… — 使用できる値はモデルごとに異なります
--resolution	512、1K、2K、4K — 解像度の段階はモデルごとに異なります
--quality	auto、low、medium、high（OpenAI）
--output-format	png、jpeg、webp（Riverflow 2.5）
--background	auto、transparent、opaque
--output-compression	0～100、OpenAI モデル
--seed	対応している場合、出力を決定的にします
--api-key	環境変数と .env の設定を上書きします
--timeout	リクエストのタイムアウト（秒、デフォルトは 300）
--retries	レート制限と 5xx レスポンスに対する再試行回数（デフォルトは 2）
--no-preflight	課金対象のリクエスト前に行う無料の機能確認をスキップします
--dry-run	リクエストを検証して表示した後、生成せずに終了します
--list-models	使用可能な値を含むカタログを表示します。必要に応じて絞り込み、終了します
--model-info	1 つのモデルで使用可能な値と料金を表示し、終了します

--size はありません。カタログ内に size パラメーターを受け付けるモデルはありません。出力の形状は --aspect-ratio と --resolution で調整します。

API の形式

スクリプトを使わずに直接リクエストする場合：

curl -s https://openrouter.ai/api/v1/images \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image",
    "prompt": "A red bicycle against a white wall",
    "aspect_ratio": "16:9"
  }'

レスポンス：

{
  "created": 1748372400,
  "data": [{ "b64_json": "<base64>", "media_type": "image/png" }],
  "usage": {
    "prompt_tokens": 4,
    "completion_tokens": 1120,
    "total_tokens": 1124,
    "cost": 0.0672,
    "completion_tokens_details": { "image_tokens": 1120 }
  }
}

b64_json は生の base64 であり、データ URL ではありません。media_type は実際の形式を示すため、ファイル名を付ける際はそれに従ってください。ベクターモデルは image/svg+xml を返し、gemini-3.1-flash-lite-image は PNG ではなく JPEG を返します。

ストリーミング（"stream": true）では、image_generation.partial_image、image_generation.completed、error イベントが出力され、最後に data: [DONE] で終了します。対応しているのは OpenAI モデルのみで、同梱のスクリプトでは使用しません。

課金は全額一括です。生成が完了した場合は全額が課金され、失敗した場合は課金されません。つまり、パラメーターが拒否されても時間がかかるだけで、料金は発生しません。ストリーミングのプレビュー画像は別途課金されません。API キーを持ち込むアカウントでは、usage.cost は 0 と表示され、実際の金額は cost_details.upstream_inference_cost に記録されます。スクリプトは実行が無料だったと誤って報告せず、この金額を表示します。

費用

画像単位の料金が設定されたモデルは予測しやすく、Seedream は $0.04、Recraft v4.1 は $0.035（ベクターは $0.08、pro は $0.21）、Riverflow 2.5 fast は $0.019、pro は $0.13～0.17、Grok は $0.05～0.07 です。

Gemini、OpenAI、MAI は出力トークン単位で課金され、解像度に応じて料金が変わります。4K 画像は 1K 画像のおよそ 16 倍の料金です。実測では、1K の gemini-3.1-flash-lite-image による画像生成は出力トークン数が 1120 で、料金は $0.034 です。同じサイズの場合、gemini-3.1-flash-image はその 2 倍、gemini-3-pro-image は 4 倍の料金です。低解像度で安価なモデルを使って下書きを作成し、サイズを上げるのは最後にしましょう。

注意事項と留意点

• モデルにテキストを任せてはいけません。 生成画像内の単語は、スペルが間違っていたり、文字化けしていたり、でたらめに作られていたりします。「文字なし」と指定し、実際の文字はLaTeX、PowerPoint、またはHTMLで重ねてください。ラベルが重要な場合は、scientific-schematicsを使用してください。
• 生成画像はイラストであり、証拠にはなりません。 測定されたものを示す画像ではありません。顕微鏡画像、画像診断、ゲル、または装置の出力として提示してはいけません。結果を報告する図の代わりに使用せず、キャプションでイラストであることを明記してください。NatureとScienceはいずれも生成AI画像の開示を求めており、いくつかの学術誌では、コンセプトアートであることが明確に示されている場合を除き、使用を禁止しています。投稿前に投稿先の規定を確認してください。
• 生成には有料API呼び出しが必要です。文言を調整している間は、低価格のモデルと低解像度を優先してください。
• 生成には、モデルと解像度に応じておよそ5～60秒かかります。
• 参照画像はOpenRouterにアップロードされます。未発表データや機密データ、患者画像、または公開差し止め中のデータは送信しないでください。
• APIキーをハードコードしてはいけません。環境変数またはGitの追跡対象外にした.envに保存してください。
• 編集時は、具体的にプロンプトを指定してください。「空を夕焼け色に変える」は「空を編集する」より適切です。
• 拒否された場合は、不適切な画像ではなく、コンテンツポリシーへの言及を含むHTTP 400または403が返されます。プロンプトを言い換えてください。臨床や解剖に関する対象は、依頼内容に比して過剰にモデレーションに抵触することがあります。
• レート制限と5xx応答は自動的に再試行されます。4xxは、依頼自体を変更する必要があるため、再試行されません。

関連スキル

• scientific-schematics — 技術図、フローチャート、回路、経路図
• scientific-slides — 生成したビジュアルを埋め込んだプレゼンテーション
• latex-posters — メイン画像を埋め込んだポスター

エージェントの作業手順

1. 環境を確認します。 データソース、各図で伝えるべき内容、対象媒体（学術誌、ポスター、スライド）を確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値については、推測せずに質問してください。
3. まず小規模なものを実行します。 最終サイズで図を1つレンダリングし、全体を作成する前に判読性を確認します。
4. 上記の手順と参照資料を使って、タスク全体を実行します。
5. 結果を検証します。 軸、単位、エラーバーにラベルが付いて定義されていること、色が色覚多様性に配慮していること、数値が基礎データと一致していることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を明記します。

次のことが起きた場合	次のように対応します
最終サイズでテキストが読めない	文字を小さくするのではなく、フォントサイズを大きくするか、パネルを簡略化します。
この手順に記載された関数、フラグ、またはエンドポイントがインストール済みのバージョンにない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。APIをでっち上げてはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 図の見栄えをよくするためにデータを改変してはいけません。画像調整は一律に適用し、その内容を開示します。
• ここに記載されているバージョン固有の詳細は古い可能性があります。インストール済みバージョンの公式ドキュメントで確認してください。
• 費用が発生する操作、共有GPUやクラウドのクォータを消費する操作、個人データや患者データにアクセスする操作、または取り消せない操作の前には、ユーザーに確認してください。