nanobanana-image-generation

Nanobanana 画像生成

概要

このスキルでは、以下の 2 つのモードが利用できます。

• image モード 公式の generateContent フローを通じた Gemini または Nanobanana による生成と編集
• plot モード 数値データから、出版物向けスタイルの図を Python または matplotlib で正確に描画

機構図、グラフィカルアブストラクト、デバイスの模式図、スタイルを合わせた描き直し、図を中心とした作業には image モードを使用します。 数値の正確性を保つ必要がある棒グラフ、傾向曲線、ヒートマップ、散布図、複数パネルの図には plot モードを使用します。

実行時の方針：

• このスキルで必須の実行環境は Python であり、image と plot の両ワークフローで標準的な方法です。
• scripts/generate_image.js は、すでに Node.js を使用している環境向けの任意の互換 CLI であり、レジストリのゲーティングにおいて必須の実行環境ではありません。

Codex で作業しているユーザーが自然言語でプロットを説明した場合、JSON 仕様を手書きするよう求めないでください。Codex がリクエストを内部的なプロットリクエストまたは仕様に変換し、プロット用スクリプトを実行してください。

image モードでは、Google の公式サンプルに従い、以下を置き換えてください。

• API キーをプロバイダーのキーに置き換える
• ベース URL を選択した Google 互換の Gemini エンドポイントに置き換える

このスキルでは、OpenAI 形式の /images/generations または /images/edits ルートを使用しないでください。

添付ファイルのみを入力に使用する場合

画像がチャットの添付ファイルとしてのみ存在し、プラットフォームからローカルファイルパスが提供されない場合、スクリプトから直接アップロードできると説明しないでください。

次のルールに従ってください。

1. ユーザーがアップロードした元画像のピクセルを正確に編集する必要がある場合は、まずローカルファイルパスを尋ねてください。
2. 近い画像の再作成でよい場合は、添付画像を目視で分析し、元の構図とスタイルを可能な限り忠実に保った新しい画像を生成してください。

「この添付画像内の英語のテキストを中国語に置き換えて」のようなリクエストでは、ピクセルを正確に維持した編集が不可能な場合、再作成による代替ワークフローを使用できます。

クイックスタート

事前確認：

• plot モードはローカルのみで動作し、API 認証情報や外部ネットワークへのアクセスは必要ありません。
• image モードでは、プロンプトのテキスト、API 認証情報、および --input-image ファイルが、設定済みの Gemini 互換エンドポイントに送信されます。
• 他のプロバイダーを意図的に信頼する場合を除き、Google の公式エンドポイントを優先してください。
• サードパーティのエンドポイントを使用する場合は、--allow-third-party または NANOBANANA_ALLOW_THIRD_PARTY=1 を必須とし、明示的な信頼の判断として扱ってください。

環境変数を設定します。

export NANOBANANA_API_KEY="your-provider-key"
export NANOBANANA_BASE_URL="https://generativelanguage.googleapis.com"
export NANOBANANA_MODEL="gemini-3.1-flash-image-preview"

任意のサードパーティプロバイダー：

export NANOBANANA_BASE_URL="https://api.zhizengzeng.com/google"
export NANOBANANA_ALLOW_THIRD_PARTY=1

API キーをコマンドラインに表示したくない場合は、ファイルに保存して次を使用します。

export NANOBANANA_API_KEY_FILE="$PWD/.secrets/nanobanana_api_key"

画像を生成します。

python3 scripts/generate_image.py "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"

画像を編集します。

python3 scripts/generate_image.py "Using the provided image, change only the blue sofa to a vintage brown leather Chesterfield sofa. Keep everything else exactly the same." --input-image ./living-room.png

ラベルを翻訳して、添付された図を再作成します。

python3 scripts/generate_image.py "Recreate the attached pastel technical diagram with the same layout, icons, arrows, and hand-drawn style. Replace all visible English labels with natural Simplified Chinese. Keep the composition unchanged." --aspect-ratio 16:9 --image-size 2K

安全に関する注意：

• scripts/build_materials_figure_prompt.py と --print-prompt はローカルのみで動作し、データをネットワーク経由で送信しません。
• 実際のプロンプトのテキスト、API キー、ユーザー提供の入力画像が送信されるのは、設定済みのプロバイダーに対して生成スクリプトを実行した場合のみです。
• 公式ではない Gemini 互換エンドポイントを使用するには、--allow-third-party または NANOBANANA_ALLOW_THIRD_PARTY=1 による明示的な確認が必要です。
• シェルの履歴にキーを表示したくない場合は、インラインの --api-key より NANOBANANA_API_KEY_FILE を優先してください。

ワークフロー

まずモードを選択します。

1. ユーザーが数値データを提供し、正確なプロットを必要としている場合は、plot モードを使用します。 references/publication-plot-api.md を読み、scripts/plot_publication_figure.py を実行します。 自然言語でのリクエストの場合は、references/natural-language-plot-workflow.md も読みます。
2. ユーザーが模式図、グラフィカルアブストラクト、または画像編集のワークフローを必要としている場合は、image モードを使用します。 以下の Gemini generateContent フローに従います。

image モードの場合：

1. 公式の Gemini リクエスト形式を維持します。 X-goog-api-key を指定して POST /v1beta/models/{model}:generateContent を使用します。
2. プロンプトのテキストと画像入力を contents[].parts に格納します。 テキストのみの生成ではテキストパートを 1 つ使用します。画像編集では、インライン画像パートを 1 つ以上追加します。
3. 画像オプションは generationConfig.imageConfig に指定します。 公式ドキュメントに合わせて、--aspect-ratio と --image-size を優先します。
4. 材料科学の図の場合は、まず最終的なプロンプトを作成することをお勧めします。 API リクエストを送信する前にプロンプトを確認または調整する場合は、python3 scripts/build_materials_figure_prompt.py --materials-figure ... を使用します。
5. 論文掲載向けの研究図の場合は、必要に応じて同梱のデザインガイドを読み込みます。 基本スタイル、配色の意味、タイポグラフィ、パネルの構成については、references/publication-figure-design.md を読みます。
6. 図にグラフ形式のパネルが含まれる場合は、references/publication-chart-patterns.md を読みます。 これらのパターンを使って、グループ化された棒グラフ、ヒートマップ、傾向レイアウト、独立した凡例、横長の比較パネルを指定します。
7. candidates[0].content.parts[].inlineData から画像出力を保存します。 テキストパートも返された場合は、それも保存します。
8. 元画像が添付ファイルのみの場合は、正確な編集と再作成のどちらかを選びます。 正確に編集する場合はローカルパスを尋ねます。ユーザーが結果を希望し、見た目を合わせた描き直しを受け入れる場合は、再作成を使用します。

plot モードの場合：

1. references/publication-plot-api.md を読みます。
2. ユーザーが自然言語で依頼している場合は、プロットの意図とデータ構造を推測します。 ユーザーが低レベルの制御を明示的に希望しない限り、内部仕様を作成するようユーザーに求めないでください。
3. 簡潔な内部翻訳の場合は、必要に応じてリクエスト JSON を作成し、scripts/build_plot_spec.py で展開します。
4. トップレベルに style、layout、panels を含む JSON 仕様を作成または生成します。
5. bar、trend、heatmap、scatter、legend、または empty パネルを使用します。
6. 次のコマンドでレンダリングします。

python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py spec.json

7. 正確な PNG、PDF、または SVG 出力を書き出します。

環境

必須：

• NANOBANANA_API_KEY
• NANOBANANA_BASE_URL 明示的に設定する必要があります。Google の公式エンドポイントは https://generativelanguage.googleapis.com です。

任意：

• NANOBANANA_MODEL デフォルト：gemini-3.1-flash-image-preview
• NANOBANANA_TIMEOUT デフォルト：120
• NANOBANANA_API_KEY_FILE API キーを含むファイルへのパスです。コマンド履歴やコマンドログにキーを表示したくない場合は、こちらをお勧めします。
• NANOBANANA_ALLOW_THIRD_PARTY 公式ではない Gemini 互換プロバイダーに API キーとユーザー提供ファイルを意図的に送信する場合に限り、1 に設定します。

スクリプト

• scripts/generate_image.py 公式の Gemini generateContent リクエスト形式に従う Python CLI です。
• scripts/generate_image.js 同じリクエスト形式の Node.js CLI です。
• scripts/plot_publication_figure.py JSON 仕様から出版物向けの図を正確に作成する Python CLI です。
• scripts/build_plot_spec.py 簡潔なリクエスト JSON を完全なプロット仕様に展開する Python CLI です。

共通オプション：

• --input-image ./source.png
• --prompt-file ./background.md
• --aspect-ratio 16:9
• --image-size 2K
• --text-only
• --thinking-level high
• --include-thoughts
• --materials-figure mechanism-figure
• --lang zh
• --style-note "Nature Energy style"
• --print-prompt
• --allow-third-party
• --api-key-file ./.secrets/nanobanana_api_key

デフォルトの出力先：

• 現在の Codex 作業ディレクトリを基準とした ./output/nanobanana/
• ユーザーが別のフォルダーを明示的に希望した場合に限り変更します

決定論的なプロット：

python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py ./spec.json \
  --out-path ./output/plots/result \
  --formats png pdf svg \
  --dpi 300

自然言語に適した内部ワークフロー：

python3 skills/nanobanana-image-generation/scripts/build_plot_spec.py ./request.json --out ./spec.json
python3 skills/nanobanana-image-generation/scripts/plot_publication_figure.py ./spec.json

公式のマッピング

Google の公式サンプル：

• api_key="GEMINI_API_KEY"
• base_url="https://generativelanguage.googleapis.com"

サードパーティプロバイダー向けの置き換え：

• api_key="your_provider_api_key"
• base_url="your_google_compatible_endpoint"
• allow_third_party=true

Zhizengzeng の任意のサンプル：

• api_key="your_zzz_api_key"
• base_url="https://api.zhizengzeng.com/google"
• allow_third_party=true

その他はすべて、公式の Gemini ドキュメントに準拠させてください。

プロンプトのルール

• 生成では、キーワードを羅列するのではなく、シーンを説明してください。
• 編集では、変更せずに維持するものを明示してください。
• 複数画像を使うワークフローでは、各参照画像の役割を説明してください。
• 画像の忠実度が重要な場合は、英語または zh-CN のプロンプトを優先してください。
• 添付画像のみを翻訳するタスクでは、再生成した画像からテキストが漏れないよう、書き換える必要があるラベルをすべて列挙してください。
• レイアウトの忠実度が重要な場合は、アイコンの位置、矢印、間隔、階層、読み順を維持するよう明示してください。
• 出版物向けの図では、色の意味上の役割、パネルの順序、矢印の関係、中立のままにする要素を指定してください。
• 図中のテキストは短くしてください。画像に埋め込む段落のような注釈ではなく、簡潔なラベルや凡例項目を優先してください。
• 図がプロットに似ている場合は、概念図、スタイルを合わせた描き直し、または定量的な完全再現のいずれかを明記してください。

材料科学の図を手早く作成

ユーザーが材料科学論文の図、ジャーナル向けの科学模式図、グラフィカルアブストラクト、メカニズム図、合成ワークフロー図、微細構造と特性の関係図、デバイス構成図、または特性評価計画図を求めた場合は、プロンプトを一から作成するのではなく、同梱の材料科学テンプレートを使用してください。

ワークフロー：

1. references/materials-science-figure-template.mdを読みます。
2. 最も近いサブタイプを選びます：
   • graphical-abstract
   • mechanism-figure
   • device-architecture
   • processing-workflow
3. 出力言語を選びます：
   • en
   • zh
4. ユーザーの科学的内容をScientific Backgroundの欄に挿入するか、スクリプトのショートカットを直接使います。
5. 因果関係、配色、タイポグラフィ、レイアウト、根拠のない主張を避けることに関するテンプレートの制約を守ります。
6. ユーザーが正確な数値を提示していない場合は、ラベルを定性的な表現にするか、データを捏造せずにプレースホルダーを明示的に使用します。
7. ユーザーが特定のジャーナルのスタイルを希望する場合は、テンプレートを書き換えず、その希望をテンプレートの後に追加します。
8. 科学的背景が長い場合は、Markdown ファイルに記述し、--prompt-fileまたはscripts/build_materials_figure_prompt.py --background-file ...を使用します。内容を1つのシェル引数に無理に詰め込まないでください。
9. プロンプトを調整する場合は、次の資料を参照します：
   • references/materials-science-figure-template.md
   • references/publication-figure-design.md
   • references/publication-chart-patterns.md

研究図のデザイン統合

このスキルには、figures4papersプロジェクトをもとに要点をまとめた、出版用図の実践ガイドが含まれています。Nanobanana の出力が、一般的なAIアートではなく、ジャーナル掲載用の図に見えるように活用してください。

必要に応じて、参考ファイルを読みます：

• references/publication-figure-design.md 図全体のアートディレクションに使用します。タイポグラフィ、配色の意味、パネルの階層、白背景の方針、凡例の扱い、印刷に適した簡素化について説明しています。
• references/publication-chart-patterns.md 図に棒、傾向線、ヒートマップ、比較マトリクス、または独立した凡例パネルが含まれる場合に使用します。

プロンプトを作成する際は、次のルールを適用します：

• 全体の構成をシンプルかつ高コントラストにし、パネルを中心に組み立てます。
• 主要なメカニズムまたは提案手法には青、改善には緑、対比には赤、足場や背景カテゴリには中間色のグレーを使用します。
• 短く専門的なラベル、枠のない凡例、すっきりした白背景を指定します。
• パネル間で一貫した視覚表現を保ち、同じ色が常に同じ相、状態、または手法を意味するようにします。
• グラフ形式の図では、モデルに出版用のレイアウトとスタイルを模倣するよう指定します。ただし、提供された元データや参照画像から図を再作成する場合を除き、定量的な正確さを示唆しないでください。

定量表現の範囲

このスキルが得意とするのは、次の内容です：

• グラフィカルアブストラクト
• メカニズム図
• デバイス模式図
• プロセスワークフロー
• グラフ形式の概念パネル
• 既存の論文図をスタイルに合わせて描き直すこと

このスキルは、定量的なプロットの正確さを保証するものではありません。正確な棒の高さ、ヒートマップの正確な値、または生データに基づく忠実な軸目盛りの計算が必要な場合、信頼できる参照画像からの描き直しを明示的に依頼されていない限り、Nanobanana はレイアウトまたはビジュアルの方向性を決めるツールとして扱ってください。

正確にプロットするには、plotモードに切り替え、references/publication-plot-api.mdとscripts/plot_publication_figure.pyを使用します。

Python のショートカット：

python3 scripts/generate_image.py "paste the scientific background here" \
  --materials-figure mechanism-figure \
  --lang en \
  --style-note "Benchmark the figure against Nature Materials aesthetics." \
  --aspect-ratio 4:3 \
  --image-size 2K

JavaScript のショートカット：

node scripts/generate_image.js "paste the scientific background here" \
  --materials-figure graphical-abstract \
  --lang zh \
  --aspect-ratio 4:3 \
  --image-size 2K

プロンプトのみの事前確認：

python3 scripts/build_materials_figure_prompt.py \
  --materials-figure mechanism-figure \
  --lang en \
  --background-file ./background.md \
  --style-note "Nature Materials aesthetic with concise panel labels."

失敗時の対応

• API が 401 または 403 を返す場合は、NANOBANANA_API_KEY を確認してください。
• CLI がベース URL が設定されていないと表示する場合は、NANOBANANA_BASE_URL を設定するか、--base-url を渡してください。
• CLI が公式ではないエンドポイントを拒否する場合は、そのプロバイダーを意図的に使用する場合に限り、--allow-third-party を追加するか、NANOBANANA_ALLOW_THIRD_PARTY=1 を設定してください。
• API が 404 を返す場合は、リクエストが /v1beta/models/{model}:generateContent に送信されていることを確認してください。
• プロバイダーがモデルは存在しないと表示する場合は、公式ドキュメントとプロバイダーの対応モデル一覧で、正確なモデル名を確認してください。
• 画像が返されない場合は、candidates[0].content.parts を調べ、リクエストで画像出力を求めていたか確認してください。
• ユーザーがチャットの添付ファイルのみを提供し、ファイルパスを指定していない場合、プラットフォームが実際に添付ファイルのバイトデータを公開していない限り、結果を正確な編集として説明しないでください。

参考資料

• 公式のリクエスト形式については、references/api-reference.md を参照してください。
• 生成と編集のプロンプトのひな型については、references/prompt-templates.md を参照してください。
• 材料科学論文の図を生成する場合は、references/materials-science-figure-template.md を参照してください。
• figures4papers をもとにした、論文掲載向けの研究図のルールについては、references/publication-figure-design.md を参照してください。
• グラフと複数パネルのレイアウトパターンについては、references/publication-chart-patterns.md を参照してください。
• 数値データから正確にプロットする方法については、references/publication-plot-api.md を参照してください。
• ユーザーが自然言語で正確なプロットを説明し、Codex がそれを内部のプロットリクエストに変換する必要がある場合は、references/natural-language-plot-workflow.md を参照してください。