nanobanana

Nano Banana - AI 画像生成

Google Gemini モデルを使用して画像を生成、編集します。2 つのモデルに対応しています。

• Pro (gemini-3-pro-image-preview) — 高品質、複雑なプロンプト、思考モード
• Flash (gemini-2.5-flash-image) — 高速、低コスト、反復作業に最適

前提条件

必須：

• GEMINI_API_KEY — Google AI Studio から取得してください
• uv（推奨）、または google-genai をインストールした Python 3.10 以降

uv を使用する場合（推奨 — セットアップ不要）： 依存関係は PEP 723 にインラインで宣言されており、初回実行時に自動でインストールされます。python3 の代わりに uv run を使用するだけです。

pip を使用する場合（代替手段）：

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

クイックスタート

デフォルトの出力先： 画像は自動的に ~/Downloads/nanobanana_<timestamp>.png に保存されます。ユーザーが保存先を指定しない限り、-o は指定しないでください。ユーザーがディレクトリを含まないファイル名（例：「robot.png という名前で保存」）を指定した場合は、-o ~/Downloads/robot.png を使用してください。

画像を生成する：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "a cute robot mascot, pixel art style"

既存の画像を編集する：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "make the background blue" -i input.jpg

高速な反復作業に Flash モデルを使用する：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "quick sketch of a cat" --model flash

複数画像の参照（スタイル＋被写体）：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "apply the style of the first image to the second" \
  -i style_ref.png subject.jpg

アスペクト比と解像度を指定して生成する：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "cinematic landscape" --ratio 21:9 --size 4K

特定の場所に保存する：

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "logo design" -o ~/Projects/brand/logo.png

モデル選択ガイド

	Pro（デフォルト）	Flash
速度	遅め	約 2～3 倍高速
コスト	高め	低め
テキスト描画	良好	不安定
複雑なシーン	優秀	十分
思考モード	あり	なし
最適な用途	最終的な制作画像	試行、下書き、一括生成

目安： 試行や一括生成には Flash、最終出力には Pro を使用してください。

スクリプトリファレンス

scripts/generate.py

画像生成のメインスクリプトです。

Usage: generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -o, --output PATH     Output file path (default: ~/Downloads/nanobanana_<timestamp>.png)
  -i, --input PATH...   Input image(s) for editing / reference (up to 14)
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio (1:1, 16:9, 9:16, 21:9, etc.)
  -s, --size SIZE       Image size: 1K, 2K, or 4K (default: standard)
  --search              Enable Google Search grounding for accuracy
  --retries N           Max retries on rate limit (default: 3)
  -v, --verbose         Show detailed output

対応アスペクト比：

• 1:1 — 正方形（デフォルト）
• 2:3、3:2 — 縦向き／横向き
• 3:4、4:3 — 標準
• 4:5、5:4 — 写真
• 9:16、16:9 — ワイドスクリーン
• 21:9 — ウルトラワイド／シネマティック

画像サイズ：

• 1K — 高速、詳細度は低め
• 2K — 詳細度を向上（2048px）
• 4K — 最高品質（3840px）、テキスト描画に最適

scripts/batch_generate.py

連番の名前を付けて複数の画像を生成します。

Usage: batch_generate.py [OPTIONS] PROMPT

Arguments:
  PROMPT                Text prompt for image generation

Options:
  -n, --count N         Number of images to generate (default: 10)
  -d, --dir PATH        Output directory (default: ~/Downloads)
  -p, --prefix STR      Filename prefix (default: "image")
  -m, --model MODEL     Model: 'pro' (default), 'flash', or full model ID
  -r, --ratio RATIO     Aspect ratio
  -s, --size SIZE       Image size (1K/2K/4K)
  --search              Enable Google Search grounding
  --retries N           Max retries per image on rate limit (default: 3)
  --delay SECONDS       Delay between generations (default: 3)
  --parallel N          Concurrent requests (default: 1, max recommended: 5)
  -q, --quiet           Suppress progress output

例：

uv run ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py "pixel art logo" -n 20 --model flash -d ./logos -p logo

Python API

直接インポート（別のスキルのスクリプトから）：

注： Python モジュールとしてインポートする場合、呼び出し元スクリプトの環境で google-genai を利用できる必要があります。uv run を使用する場合は、独自のスクリプトに PEP 723 の dependencies ブロックを追加してください（以下のパターン 2 の例を参照）。

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from generate import generate_image, edit_image, batch_generate

# Generate image
result = generate_image(
    prompt="a futuristic city at night",
    output_path="city.png",
    aspect_ratio="16:9",
    image_size="4K",
    model="pro",
)

# Edit existing image
result = edit_image(
    prompt="add flying cars to the sky",
    input_path="city.png",
    output_path="city_edited.png",
)

# Multi-image reference
result = generate_image(
    prompt="combine the color palette of the first with the composition of the second",
    input_paths=["palette_ref.png", "composition_ref.png"],
    output_path="combined.png",
)

戻り値の構造（常に存在）：

{
    "success": True,       # or False
    "path": "/path/to/output.png",  # or None on failure
    "error": None,         # or error message string
    "metadata": {
        "model": "gemini-3-pro-image-preview",
        "prompt": "...",
        "aspect_ratio": "16:9",
        "image_size": "4K",
        "use_search": False,
        "input_images": None,        # or list of paths
        "text_response": "...",      # optional text from model
        "thinking": "...",           # Pro model reasoning (when available)
        "timestamp": "2025-01-26T...",
    }
}

下流スキルとの統合ガイド

パターン 1：CLI ラッパー（シンプルな用途に推奨）

# In your skill's script:
uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py "{prompt}" --model flash --ratio 16:9 -o output.png

パターン 2：カスタムのデフォルト値で Python インポート

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-genai>=1.0.0",
# ]
# ///

import sys
from pathlib import Path

NANOBANANA_DIR = Path("${CLAUDE_SKILL_DIR}/scripts")
sys.path.insert(0, str(NANOBANANA_DIR))
from generate import generate_image

def generate_thumbnail(prompt: str, output_path: str) -> dict:
    """Generate a YouTube thumbnail with project defaults."""
    return generate_image(
        prompt=prompt,
        output_path=output_path,
        aspect_ratio="16:9",
        image_size="2K",
        model="flash",
        max_retries=3,
    )

パターン 3：進行状況を追跡しながら一括処理

from batch_generate import batch_generate

def on_progress(completed, total, result):
    print(f"Progress: {completed}/{total}")

results = batch_generate(
    prompt="logo concept",
    count=20,
    output_dir="./logos",
    prefix="logo",
    model="flash",
    aspect_ratio="1:1",
    on_progress=on_progress,
)

successful = [r for r in results if r["success"]]

パターン 4：シリーズ向けの連続生成

下流のスキルで、一貫したスタイルの画像を複数枚必要とする場合（例：ニュースレターのビジュアル、サムネイルの A/B バリエーション）は、アンカー画像と参照画像を使うパターンを使用してください。

from generate import generate_image

# Step 1: Generate the style anchor
anchor = generate_image(
    prompt="warm illustration style, earth tones, soft gradients, clean lines",
    output_path="anchor.png",
    model="pro",
)

# Step 2: Generate each image in the series, referencing the anchor
subjects = ["laptop on desk with coffee", "person reading a book", "sunrise over mountains"]
series_paths = [anchor["path"]]

for i, subject in enumerate(subjects):
    result = generate_image(
        prompt=f"{subject}, matching the visual style and color palette of the reference image exactly",
        input_paths=[anchor["path"]],  # always include the anchor
        output_path=f"series_{i+1:02d}.png",
        model="pro",
    )
    if result["success"]:
        series_paths.append(result["path"])

連続生成のパターン全体は、以下の連続生成セクションに記載されています。

環境変数

変数	説明	デフォルト
GEMINI_API_KEY	Google Gemini API キー	必須
IMAGE_OUTPUT_DIR	デフォルトの出力ディレクトリ	~/Downloads

機能

テキストから画像を生成

テキストの説明から画像を作成します。どちらのモデルも、以下の画像生成を得意としています。

• 写実的な画像
• アートスタイル（ピクセルアート、イラストなど）
• 商品写真
• 風景やシーン

画像編集

自然言語で既存の画像を変換します。

• スタイル変換
• オブジェクトの追加／削除
• 背景の変更
• 色の調整

複数画像の参照

以下の用途に、最大 14 枚の参照画像を指定できます。

• シリーズを通したスタイルの一貫性
• 被写体の一貫性（同じキャラクター、異なるポーズ）
• ブランドに一貫した画像生成
• スタイルと被写体の組み合わせ

高解像度の出力

• 1K — 生成が速く、ドラフトに適しています
• 2K — 詳細が向上します（2048px）
• 4K — 最高品質です（3840px）。テキストの描画に最適です

Google 検索によるグラウンディング

事実に即した画像を生成するには、次の要素を含める場合に --search を有効にしてください。

• 実在の人物、場所、ランドマーク
• 時事問題
• 特定の製品やブランド

自動再試行

レート制限エラーは、指数バックオフを使用して自動的に再試行されます（デフォルト：3 回）。呼び出し元での操作は不要です。

SynthID ウォーターマークに関する注意

Gemini で生成されるすべての画像には、目に見えない SynthID デジタルウォーターマークが含まれています。これは自動的に付与され、無効化できません。また、一般的な変換（サイズ変更、切り抜き、圧縮）を行っても残ります。ウォーターマークのない出力が必要な用途では、この点にご注意ください。

逐次生成

一連の画像で視覚的な一貫性を保つには、逐次生成を使用します。基本的な手法は、まずアンカー画像を生成し、その後の各画像の参照画像として（-i）渡すことです。

パターン 1：スタイルボードによるアンカリング

一連の画像の視覚的なアイデンティティを確立するアンカー画像を 1 枚生成します。その後のすべての画像で、この画像を参照します。

使用する場面： ニュースレター用のビジュアルシリーズ、A/B テスト用のサムネイルのバリエーション、ブランドの一貫性を保った画像の一括生成。

ワークフロー：

1. スタイル、配色、雰囲気を強調したプロンプトでアンカー画像を生成します。

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "modern flat illustration style, warm earth tones, soft gradients, clean lines, \
  minimal detail, cozy atmosphere" \
  --model pro -o anchor.png

2. アンカーを参照して、その後の各画像を生成します。

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "a laptop on a desk with coffee, matching the visual style, color palette, \
  and lighting of the reference image exactly" \
  -i anchor.png --model pro -o image_01.png

3. シリーズ内の各画像について、常に同じアンカーを参照しながら手順 2 を繰り返します。

ヒント： Flash でアンカーをすばやく下書きし、気に入ったスタイルが見つかったら Pro で再生成します。

パターン 2：被写体の一貫性

異なるシーンやポーズでも、同じキャラクターや被写体の見た目を一貫させます。

使用する場面： さまざまな状況に登場するマスコット、製品写真のシリーズ、繰り返し登場するキャラクター。

ワークフロー：

1. 外見を明確かつ詳細に説明して、最初の被写体を生成します。

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "a friendly robot mascot with round blue body, orange antenna, large expressive eyes, \
  simple geometric design, standing front-facing on white background" \
  --model pro -o subject_front.png

2. 被写体を参照して、新しいシーンを生成します。

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "the same robot character from the reference image, now sitting at a desk typing, \
  same proportions and colors, office background" \
  -i subject_front.png --model pro -o subject_office.png

3. 一貫性をさらに高めるには、過去に生成した画像のうち特に優れたものを 2～3 枚参照します。

uv run ${CLAUDE_SKILL_DIR}/scripts/generate.py \
  "the same robot character from the reference images, now outdoors in a park, \
  same proportions and colors, waving at the viewer" \
  -i subject_front.png subject_office.png --model pro -o subject_park.png

パターン 3：段階的な積み重ね

長いシリーズでは、成功した出力を次の画像の参照として加え、参照画像のプールを構築します。

使用する場面： シリーズ全体を通じて一貫性を積み重ねていく必要がある、5 枚以上の画像。

ワークフロー：

1. アンカーを生成します（パターン 1 の手順 1 と同じ）。
2. アンカーを参照して 2 枚目を生成します。
3. アンカーと 2 枚目を参照して 3 枚目を生成します。
4. これを続け、-i リストには特に優れた参照画像を 3～4 枚残します。質の低い出力は除外します。

参照画像を 3～4 枚に制限する理由： 参照画像が多すぎると、スタイルのシグナルが弱まります。モデルはすべての入力を平均化するため、数が多すぎると結果の一貫性が損なわれます。目標のスタイルを最もよく表す画像だけを残してください。

参照画像の順序も重要です： -i リストの先頭にスタイルアンカーを配置してください。モデルは先に指定された参照画像にわずかに大きな重みを付けます。

ベストプラクティス

プロンプトの作成

適切なプロンプトに含める要素：

• 被写体の説明
• スタイル／美的要素
• 照明と雰囲気
• 構図の詳細
• 配色

カテゴリ別の詳細なプロンプトテンプレートと、モデル固有のヒントについては、references/prompts.md を参照してください。

一括生成のヒント

1. 選択肢を探るための一括生成には --model flash を使用します（高速で低コストです）。
2. 選択肢を探るために 10～20 個のバリエーションを生成します。
3. リクエストを逐次送信する際は、デフォルトの 3 秒の遅延でレート制限を回避できます。
4. 結果を確認し、有力な候補を Pro モデルで反復して改善します。

レート制限

• Gemini API には使用量の割り当てがあります（無料枠は約 10 RPM）。
• 指数バックオフによる自動再試行で、一時的なレート制限に対処できます。
• 大量に生成する場合は、--delay 5 を使用するか、並列数を控えめにして --parallel を使用してください。
• Google AI Studio で割り当てを確認してください。

トラブルシューティング

「uv: command not found」

• uv をインストールします：curl -LsSf https://astral.sh/uv/install.sh | sh または brew install uv

「Error: google-genai package not installed」

• 依存関係を自動インストールするため、python3 の代わりに uv run を使用します
• または、手動でインストールします：pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

「GEMINI_API_KEY environment variable not set」

• 実行する前に、環境変数 GEMINI_API_KEY を設定します

「No image in response」

• プロンプトが安全性フィルターに引っかかった可能性があります
• センシティブな内容を避けるように言い換えてみてください

「Rate limit exceeded after N retries」

• 30～60 秒待ってから、もう一度試してください
• バッチの並列処理数を減らすか、より長い待ち時間を追加します
• API のクォータを確認します

batch_generate.py のインポートエラー

• スクリプトがパスの設定を独自に処理するため、どのディレクトリからでも実行できます

今後の機能

複数ターンの対話型編集 — Gemini API は、画像を反復的に編集するためのステートフルなチャットセッション（例：「もっと青くして」→「今度は帽子を追加して」→「ズームアウトして」）をサポートしています。これには根本的に異なるステートフルアーキテクチャが必要で、現在は実装されていません。現時点でこれを必要とする下流のスキルはありません。

参考資料

• references/prompts.md — プロンプトの例、モデル固有のヒント、複数の参照画像を使うパターン
• references/gemini-api.md — エージェントのコンテキスト向けに厳選された API リファレンス