nano-banana-pro

Nano Banana Pro（Gemini 3 Pro Image）

Google の最先端モデルである Gemini 3 Pro Image を使用して、プロ品質の画像を生成、編集できます。

API の設定

Gemini API キーを環境変数として設定します。

export GEMINI_API_KEY="your-api-key-here"

API キーは https://aistudio.google.com/apikey で取得できます。

クイックスタート

API 接続のテスト

画像を生成する前に、API 認証情報を確認します。

python scripts/test_connection.py --api-key YOUR_KEY

または、環境変数を設定します。

export GEMINI_API_KEY="your-api-key-here"
python scripts/test_connection.py

テキストから画像を生成する

python scripts/generate_image.py "A futuristic cityscape at sunset, neon lights, cyberpunk style"

オプションを指定する場合：

python scripts/generate_image.py "Portrait of a cat" \
  --aspect-ratio 9:16 \
  --temperature 0.7 \
  --output ./my_images \
  --filename cat_portrait

既存の画像を編集する

python scripts/edit_image.py "Make the sky more dramatic with storm clouds" input.jpg

オプションを指定する場合：

python scripts/edit_image.py "Change car color to red" photo.png \
  --aspect-ratio 16:9 \
  --output ./edited \
  --filename red_car

主なワークフロー

1. テキストからの画像生成

使用する場面：テキストの説明に基づいて、画像を一から作成するとき。

手順：

1. references/prompting-guide.md のベストプラクティスを参考に、効果的なプロンプトを作成します
2. 適切なパラメーターを指定して生成スクリプトを実行します
3. 出力を確認し、必要に応じて調整します

例：

# High-quality product photography
python scripts/generate_image.py \
  "High-end product photography of luxury watch on black marble, dramatic single key light from top-left, reflective surface, macro lens, f/5.6, commercial quality, 4K" \
  --aspect-ratio 1:1 \
  --temperature 0.5

主な検討事項：

• 具体的で詳細なプロンプトを使用します（プロンプト作成のベストプラクティスを参照）
• 用途に適したアスペクト比を選択します
• 一貫性を重視する場合は低めの温度（0.3～0.5）、創造性を重視する場合は高めの温度（0.8～1.0）にします
• 複雑な要件には、複数ターンの編集を繰り返します

2. 画像の編集と調整

使用する場面：自然言語の指示で既存の画像を変更するとき。

手順：

1. 必要な変更点を特定します
2. 動作を表す動詞（Add、Change、Make、Remove、Replace）を使って、正確な編集指示を作成します
3. 元画像を指定して編集スクリプトを実行します
4. 複雑な変換では、複数の編集を連続して適用します

例 — 1 回の編集：

python scripts/edit_image.py \
  "Add flying birds in the upper right sky" \
  landscape.jpg \
  --output ./edited

例 — 複数ターンでの調整：

# Edit 1: Change time of day
python scripts/edit_image.py "Convert to sunset lighting" day_scene.jpg \
  --output ./step1 --filename sunset

# Edit 2: Add elements using output from step 1
python scripts/edit_image.py "Add warm street lamps glowing" ./step1/sunset_image_0_0.jpg \
  --output ./step2 --filename with_lamps

# Edit 3: Fine-tune atmosphere
python scripts/edit_image.py "Make the sky more orange and dramatic" ./step2/with_lamps_image_0_0.jpg \
  --output ./final --filename final

主な検討事項：

• どの要素を変更するか、具体的に指定します
• 位置を示す表現（「背景に」「左側に」）を使います
• 意図的に変更する場合を除き、元のアスペクト比を維持します
• 各編集は直前の結果を基に行われます

3. バッチ生成

使用する場面：複数のバリエーションや異なる画像を連続して生成するとき。

手順：

シェルスクリプトまたは Python のラッパーを作成します。

#!/bin/bash
# batch_generate.sh

PROMPTS=(
  "Modern office workspace, minimalist design"
  "Cozy coffee shop interior, warm lighting"
  "Professional meeting room, corporate aesthetic"
)

for i in "${!PROMPTS[@]}"; do
  python scripts/generate_image.py "${PROMPTS[$i]}" \
    --output ./batch_output \
    --filename "scene_$i" \
    --aspect-ratio 16:9

  echo "Generated image $((i+1))/${#PROMPTS[@]}"
  sleep 2  # Rate limiting
done

4. 参照画像に基づく生成

使用する場面：複数の画像でスタイルやキャラクターの一貫性を保つとき。

手順：

1. 参照画像を準備します（最大 14 枚）
2. 維持するスタイルやキャラクターを参照するプロンプトを作成します
3. 複数画像のアップロードには、Python SDK または API を直接使用します

Python を使った例：

from generate_image import NanoBananaProClient
from pathlib import Path
import base64

client = NanoBananaProClient(api_key="YOUR_KEY")

# Read reference images
ref_images = []
for img_path in ["ref1.jpg", "ref2.jpg", "ref3.jpg"]:
    with open(img_path, "rb") as f:
        img_data = base64.b64encode(f.read()).decode()
        ref_images.append({
            "inlineData": {
                "mimeType": "image/jpeg",
                "data": img_data
            }
        })

# Generate with references
# (Requires direct API call with multiple inlineData parts)

プロンプト作成のベストプラクティス

基本構成

最適な結果を得るため、次の形式に従います。

[Subject] + [Style/Medium] + [Lighting Details] + [Camera/Composition] + [Quality Modifiers]

例：

"Portrait of elderly craftsman | Documentary photography style | Soft window light from left | 85mm lens, f/2.8, shallow DOF | Professional editorial quality, sharp focus on eyes"

主な原則

1. 具体的にする：曖昧なプロンプトでは、ありきたりな結果になります

   • ❌ 「夕焼け」
   • ✅ 「山並みの向こうに沈むゴールデンアワーの夕日、鮮やかなオレンジと紫の雲、手前にシルエットで浮かぶ松の木」

2. 映画的な表現を使う：Nano Banana Pro は写真用語によく反応します

   • レンズ：「24mm 広角」｜「85mm ポートレート」｜「200mm 望遠」
   • 照明：「柔らかな拡散光」｜「強い直射光」｜「リムライトを使った逆光」
   • カメラ：「ローアングルショット」｜「俯瞰」｜「ダッチアングル」

3. 描写を重ねる：雰囲気、素材、ムードで奥行きを表現します

   • 「居心地のよい図書館、暖かな琥珀色の照明、革張りの椅子、高い窓の向こうに見える雨、オーク材のテーブルのティーカップから立ち上る湯気」

4. 複数ターンで調整する：シンプルに始め、段階的に仕上げます

   • ターン 1：「モダンなキッチン、白いキャビネット」
   • ターン 2：「大理石のカウンタートップを追加」
   • ターン 3：「照明を暖かくして、窓からゴールデンアワーの光を差し込ませる」

映画のようなデジタルペイントスタイル

温かみのあるゴールデンライティング、絵画的な筆致、奥行きのある雰囲気が特徴のドキュメンタリー風デジタルペイントについては、専用のスタイルガイドをご覧ください。

cinematic-style.md - 完全な手法、主要な要素、例、技術的な注意事項

クイックリファレンス：

• 温かみのあるゴールド／アンバーのライティングと、ドラマチックなリムライト
• 目に見える質感を伴う絵画的な筆致
• 背景をぼかして雰囲気を出す、ソフトなボケと被写界深度
• 高いコントラスト（深い黒と明るいハイライト）
• 温度：一貫性と創造性のバランスを取るには0.6

プロンプト作成の完全ガイドはこちら：references/prompting-guide.md

スクリプトリファレンス

generate_image.py

テキストプロンプトから画像を生成します。

パラメーター：

• prompt（必須）：画像のテキストによる説明
• --api-key：API キー（または環境変数 GEMINI_API_KEY を使用）
• --aspect-ratio：1:1 | 3:4 | 4:3 | 9:16 | 16:9（デフォルト：16:9）
• --temperature：0.0-1.0（デフォルト：0.7）
• --output：出力ディレクトリ（デフォルト：./output）
• --filename：ベースファイル名（デフォルト：generated）
• --verbose：API の完全な応答を表示

一般的な使用例：

# Quick generation
python scripts/generate_image.py "red sports car"

# High-quality consistent output
python scripts/generate_image.py "professional headshot" \
  --temperature 0.4 --aspect-ratio 3:4

# Creative exploration
python scripts/generate_image.py "abstract art" --temperature 0.9

# Debug mode
python scripts/generate_image.py "test prompt" --verbose

edit_image.py

自然言語の指示で既存の画像を編集します。

パラメーター：

• prompt（必須）：編集指示
• image（必須）：入力画像のパス
• --api-key：API キー（または環境変数 GEMINI_API_KEY を使用）
• --aspect-ratio：出力のアスペクト比
• --temperature：創造性のレベル
• --output：出力ディレクトリ（デフォルト：./output）
• --filename：ベースファイル名（デフォルト：edited）
• --verbose：API の完全な応答を表示

一般的な編集パターン：

# Localized changes
python scripts/edit_image.py "Make the car red" photo.jpg

# Atmospheric changes
python scripts/edit_image.py "Convert to night scene" day.jpg

# Add elements
python scripts/edit_image.py "Add mountains in background" landscape.jpg

# Remove elements
python scripts/edit_image.py "Remove person from left side" group.jpg

# Style transforms
python scripts/edit_image.py "Apply vintage film look" modern.jpg

test_connection.py

API の接続をテストし、認証情報を確認します。

パラメーター：

• --api-key：テストする API キー
• --json：スクリプトで使用できるよう、JSON 形式で出力

使用方法：

# Interactive test
python scripts/test_connection.py --api-key YOUR_KEY

# Automated testing
python scripts/test_connection.py --json | jq '.success'

generate_with_references.py

スタイル参照画像（最大14枚）を使って画像を生成します。

パラメーター：

• prompt（必須）：生成する画像のテキストによる説明
• references（必須）：1つ以上の参照画像のパス（最大14枚）
• --api-key：API キー（または環境変数 GEMINI_API_KEY を使用）
• --aspect-ratio：1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9（デフォルト：1:1）
• --resolution：1K | 2K | 4K（デフォルト：2K）
• --output：出力ディレクトリ（デフォルト：./output）
• --filename：ベースファイル名（デフォルト：generated）
• --verbose：詳細な出力を表示

使用方法：

# Generate avatar matching reference style
python scripts/generate_with_references.py \
  "Portrait of elderly craftsman in same artistic style as references" \
  ref1.png ref2.jpg ref3.png \
  --output ./output \
  --filename craftsman

# Character consistency across images
python scripts/generate_with_references.py \
  "Same character in a coffee shop scene" \
  character_ref1.png character_ref2.png \
  --aspect-ratio 16:9 \
  --resolution 2K

ベストプラクティス：

• プロンプトにスタイルの説明を含めます（「同じ芸術的なスタイル」「ライティングを合わせる」）
• 一貫性のある参照画像を使用します（同じアートスタイル、ライティング、カラーパレット）
• 参照画像には、キャラクター、オブジェクト、スタイルの例を使用できます
• 最大14枚：オブジェクト用に6枚、キャラクターの一貫性を保つために5枚

高度なテクニック

マルチ解像度ワークフロー

まず素早くプレビューを生成し、その後に最終画像をアップスケールします：

# 1. Quick iteration at 1K (implied by default, fastest)
python scripts/generate_image.py "concept art spaceship" \
  --filename concept_draft

# 2. Review output, refine prompt

# 3. Generate final at higher quality with refined prompt
python scripts/generate_image.py "detailed concept art of sleek sci-fi spaceship, studio lighting, 4K quality, sharp details" \
  --temperature 0.5 \
  --filename concept_final

温度の設定方法

• 0.3-0.5：商品写真、技術図、一貫性が必要な場合
• 0.7（デフォルト）：バランス型。ほとんどの使用例に適しています
• 0.8-0.9：創造的な探求、芸術的なスタイル、抽象画

アスペクト比の選択

• 1:1 - ソーシャルメディアの投稿、プロフィール画像、アイコン
• 16:9 - プレゼンテーション、YouTube のサムネイル、ウェブサイトのヘッダー
• 9:16 - モバイル向けストーリー、縦型動画のサムネイル、アプリ画面
• 4:3 / 3:4 - 従来の写真、ポートレート作品
• 4:5 - Instagram の投稿（最も近い比率として4:3を使用）

トラブルシューティング

よくある問題

1. API キーが機能しない

   # Verify key format and test
   python scripts/test_connection.py --api-key YOUR_KEY
   

2. レート制限

   • 無料枠：1 日あたり約 100 リクエスト、1 分あたり 2～5 リクエスト
   • リクエストの間に遅延を追加します：sleep 2
   • 指数バックオフを実装します（references/troubleshooting.md を参照）

3. 出力品質が低い

   • より具体的なプロンプトを使用します
   • 一貫性を高めるには、温度を下げます（0.5）
   • 品質を高める修飾語を追加します：「4K」、「professional」、「sharp focus」
   • 入力画像の解像度を確認します（編集時）

4. モデルが見つからない（404）

   • モデル名を確認します：gemini-3-pro-image-preview
   • 地域ブロックされていないか確認します（ヨーロッパ／MENA）
   • VPN または別のモデルを試します

5. コンテンツポリシー違反

   • 暴力や露骨なコンテンツへの言及を削除します
   • 著作権のあるキャラクターは避けます
   • 許可なく実在の著名人に言及しないでください
   • 表現をより控えめに言い換えます

詳しいトラブルシューティングについては、こちらを参照してください：references/troubleshooting.md

API の詳細

料金

• 1K／2K 画像：1 枚あたり $0.134
• 4K 画像：1 枚あたり $0.24
• 画像入力（編集）：1 枚あたり $0.0011

レート制限

無料枠：

• 1 日あたり約 100 リクエスト
• 1 分あたり 2～5 リクエスト
• 同時リクエスト 1 件

有料枠：

• 1 日あたり無制限（クォータに準拠）
• 1 分あたり 60 リクエスト
• 同時リクエスト 10 件

対応フォーマット

入力（編集時）：JPEG、PNG、WebP 出力：JPEG、PNG（API で指定）

API リファレンスの全内容については、こちらを参照してください：references/api-reference.md

統合パターン

Python との統合

from scripts.generate_image import NanoBananaProClient

# Initialize client
client = NanoBananaProClient(api_key="YOUR_KEY")

# Generate image
response = client.generate_image(
    prompt="Professional product photo",
    aspect_ratio="1:1",
    temperature=0.6
)

# Save results
from pathlib import Path
saved = client.save_images_from_response(
    response,
    output_dir=Path("./output"),
    base_filename="product"
)

print(f"Saved to: {saved}")

Bash／シェルのワークフロー

#!/bin/bash
# Simple workflow automation

export GEMINI_API_KEY="your-key"

# Generate multiple variations
for style in "modern" "vintage" "minimal"; do
  python scripts/generate_image.py \
    "$style office interior" \
    --filename "office_${style}" \
    --output ./variations
  sleep 2
done

echo "Generated ${#styles[@]} variations"

エラー処理パターン

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.generate_image(prompt)
            return response
        except Exception as e:
            if "429" in str(e):  # Rate limited
                wait = 2 ** attempt  # Exponential backoff
                print(f"Rate limited, waiting {wait}s...")
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

使用例

マーケティングキャンペーン

# Generate hero image
python scripts/generate_image.py \
  "Dynamic marketing hero image for tech startup, modern professional team collaborating, bright office space, cinematic color grading, 16:9" \
  --temperature 0.6 \
  --output ./campaign \
  --filename hero

# Generate social media variant
python scripts/edit_image.py \
  "Crop to square focusing on center, increase contrast" \
  ./campaign/hero_image_0_0.jpg \
  --aspect-ratio 1:1 \
  --output ./campaign \
  --filename social

コンテンツ作成

# Blog header
python scripts/generate_image.py \
  "Blog header for article about sustainable architecture, modern green building with vertical gardens, clear sky, professional editorial photography, 16:9" \
  --filename blog_header

# Thumbnail for video
python scripts/generate_image.py \
  "YouTube thumbnail style, bold composition about productivity tips, vibrant colors, text space on left third, eye-catching" \
  --aspect-ratio 16:9 \
  --filename thumbnail

製品モックアップ

# Product shot
python scripts/generate_image.py \
  "High-end product photography of minimalist desk lamp on marble surface, soft studio lighting from right, black background, commercial quality" \
  --aspect-ratio 1:1 \
  --temperature 0.4 \
  --filename product_main

# Lifestyle context
python scripts/edit_image.py \
  "Place in modern home office setting with laptop and plants" \
  product_main_image_0_0.jpg \
  --filename product_lifestyle

リソース

ドキュメントファイル

• プロンプトガイド（references/prompting-guide.md）：ベストプラクティス、例、手法
• API リファレンス（references/api-reference.md）：API ドキュメント全般、料金、SDK
• トラブルシューティング（references/troubleshooting.md）：よくある問題、解決策、エラーコード
• プロンプト例（assets/example-prompts.md）：カテゴリ別のすぐに使えるプロンプト
• Aldea アバター（references/aldea-avatars.md）：Soul Engine のペルソナ向けキャラクターテンプレート

外部リンク

• Google AI Studio：https://aistudio.google.com（API キーの取得、無料枠）
• 公式ドキュメント：https://ai.google.dev/gemini-api/docs
• 料金ページ：https://ai.google.dev/gemini-api/docs/pricing
• モデル情報：https://deepmind.google/models/gemini-image/pro/
• Vertex AI コンソール：https://console.cloud.google.com/vertex-ai（エンタープライズ）

API キーの取得

1. https://aistudio.google.com にアクセスします
2. Google アカウントでサインインします
3. 左側のサイドバーで「Get API key」をクリックします
4. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
5. API キーを生成します
6. 安全に保管します（git にコミットしないでください）

# Store in environment
export GEMINI_API_KEY="AIzaSy..."

# Or in .env file (add to .gitignore!)
echo "GEMINI_API_KEY=AIzaSy..." >> .env

ヒントとコツ

1. 結果をキャッシュする：同じ画像を再生成しないようにします
2. テンプレートを使う：繰り返し使う用途向けにプロンプトテンプレートを作成します
3. 段階的に調整する：シンプルな内容から始め、複数ターンの編集で仕上げます
4. バッチ処理は慎重に行う：レート制限を守るために遅延を追加します
5. コストを監視する：4K 画像は 2K 画像の 2 倍のコストがかかります
6. プロンプトをテストする：一貫性のテストには低い温度を使用します
7. 例から学ぶ：パターンを把握するために assets/example-prompts.md を確認します
8. 参照画像：スタイルの一貫性を保つために最大 14 枚使用します
9. 品質を高める修飾語：最良の結果を得るには、「professional」、「4K」、「sharp」を必ず含めます
10. 詳細モード：デバッグ時には --verbose フラグを使用します