---
type: skill
name: nano-banana-image
agent_ready: true
schema_version: 1
bundle_skill: true
bundle_version: "0.28.0"
scope: anwender
default_active:
  allgemein: false
  content: true
  business: false
  beratung: false
  automation: false
  image: true
conflicts_with: []
depends_on: []
trigger_words:
  - nano-banana
  - nano-banana-image
  - gemini-image
  - bildgenerierung
  - image-generation
  - bild-erzeugen
created: 2026-05-19
updated: 2026-05-19
description: "Wrapper für die Google Gemini Image Generation API (Nano Banana). Erzeugt Bilder aus Text-Prompts, unterstützt Multi-Reference-Editing für Identitäts-Konsistenz über mehrere Charaktere, transparente PNGs, Aspect-Ratio-Steuerung. Liest GEMINI_API_KEY aus der Umgebung (per Skill-Config überschreibbar). Empfohlene Setup-Methode: 1Password CLI mit op-run.sh-Wrapper."
---

# Nano Banana Image Skill

## ⛔ OBERSTE SICHERHEITSREGEL

API Keys dürfen NIEMALS:
- An das LLM (Claude) weitergegeben werden
- In Konsolenausgaben, Logs oder Fehlermeldungen erscheinen
- Per `cat`, `echo`, `print` ausgegeben werden
- In generierten Code eingebettet werden

Validierung NUR per `op read "op://..." 2>/dev/null | wc -c` (nur Länge, nie den Wert!) — falls 1Password-Setup verwendet wird.

## Hinweis bei echten Personen im Bild

Wenn eine echte Person des Anwenders abgebildet werden soll, ist zu prüfen, ob ein dedizierter Identitäts-Treuer-Portrait-Skill verfügbar ist. Sonst ist die Bildgenerierung nur für nicht-identifizierbare Szenen oder generische Charaktere zu nutzen.

Nur wenn eindeutig keine echte Person im Bild ist (Landschaften, Produkte, UI, generische Charaktere ohne Identitätsanspruch), darf dieser Skill direkt angewendet werden.

---

Dieser Skill hat zwei Modi:

1. **Generierungs-Modus** — Bilder erstellen oder bearbeiten via Google Gemini API
2. **Beratungs-Modus** — Fragen zur API, Best Practices, Parametern beantworten (KEIN Bild generieren)

**Entscheidungslogik:** Wenn der Anwender eine Frage stellt ("wie funktioniert...", "was kostet...", "welches Modell soll ich...", "Unterschied zwischen..."), beantworte die Frage direkt mit Wissen aus diesem Skill und `references/api-reference.md`. Generiere NUR dann ein Bild, wenn der Anwender explizit darum bittet oder eine Beschreibung eines gewünschten Bildes gibt.

---

## Voraussetzungen

- Python 3.11+ und die Library aus `requirements.txt`
- Umgebungsvariable mit dem API-Key (Default-Name: `GEMINI_API_KEY`). Der Skill liest ausschließlich über `os.environ.get(...)` — die Setup-Methode (Shell-Profil, .env-Datei, 1Password CLI mit op-run.sh-Wrapper) ist Anwender-Wahl.
- Optional: Skill-Config (`skill.config.yaml`) kann den ENV-Var-Namen über `features.api_key_env_var` überschreiben.

---

## Modell-Übersicht

| Modell-Name | Modell-ID | API-Methode | Priorität |
|---|---|---|---|
| **Nano Banana 2** | `gemini-3.1-flash-image-preview` | `generate_content` | Default |
| **Nano Banana 1** | `gemini-2.5-flash-image` | `generate_content` | Legacy |
| **Nano Banana Pro** | `gemini-3-pro-image-preview` | `generate_content` | Premium |
| **Imagen 4** | `imagen-4.0-generate-001` | `generate_images` | Text-to-Image only |
| **Imagen 4 Ultra** | `imagen-4.0-ultra-generate-001` | `generate_images` | Höchste Qualität |
| **Imagen 4 Fast** | `imagen-4.0-fast-generate-001` | `generate_images` | Schnellste |

**Wenn der Anwender kein Modell nennt, immer `gemini-3.1-flash-image-preview` (Nano Banana 2) verwenden.**

### Wann welches Modell empfehlen

| Anwendungsfall | Empfehlung | Grund |
|---|---|---|
| Standard Bildgenerierung | NB2 | Bestes Preis/Leistungs-Verhältnis, Streaming |
| Komplexe Kompositionen, Infografiken | NB2 mit `thinking_level="high"` | Besseres Reasoning |
| Text im Bild (Logos, Werbung) | NB2 oder NB Pro | Gutes Text-Rendering |
| Bildbearbeitung / Multi-Turn | NB2 oder NB Pro | Conversational Editing |
| Batch-Generierung ohne Bearbeitung | Imagen 4 | Einfacher, günstiger |
| Deterministische Reproduktion (Seed) | Imagen 4 | Einziges Modell mit Seed-Support |
| 4K-Premium-Assets | NB Pro | Höchste Detailtreue |
| Character Consistency (viele Referenzbilder) | NB2 (bis 14) oder NB Pro | Multi-Referenz |
| Echtzeit-Daten (Wetter, Sport, Nachrichten) | NB2 + Google Search | Web + Image Search |
| Echtzeit-Daten mit Bild-Referenz aus Web | NB2 + Image Search | Einziges Modell mit Image Search |
| Schnelle Prototypen / Thumbnails | Imagen 4 Fast oder NB2 mit 512 | Niedrigste Latenz |

---

## Schritt 1: API-Key Setup

Der Skill liest `GEMINI_API_KEY` aus der Umgebung. Der Skill ist agnostisch gegenüber Setup-Methode:

- Shell-Profil: `export GEMINI_API_KEY=...` in `.bashrc`/`.zshrc`/PowerShell-Profil
- `.env`-Datei: `GEMINI_API_KEY=...` im Projekt-Root oder Skill-Verzeichnis
- 1Password CLI mit op-run-Wrapper (empfohlen für Sicherheit, siehe INSTALL.md)

Der Skill ruft niemals `cat`, `echo`, `print` oder ähnliche Befehle gegen .env-Dateien auf. Validierung nur per `find_api_key.py` (gibt ausschließlich "OK" + Länge aus, nie den Wert).

### Sicherheit: API Keys — KRITISCH

NIEMALS API Keys, Secrets oder Teile davon in den LLM-Kontext bringen.

Dies ist eine harte Sicherheitsregel ohne Ausnahmen:

- NIEMALS `.env`-Dateien lesen, anzeigen, mit `cat`/`Read`/`grep`/`Bash` öffnen
- NIEMALS API Keys (auch nicht teilmaskiert wie `AIza...xyz`) in Ausgaben, Befehlen oder Skripten anzeigen
- NIEMALS den Quellpfad einer `.env`-Datei ausgeben (verrät Dateisystem-Struktur)
- NIEMALS `--api-key` oder ähnliche CLI-Flags mit Key-Werten verwenden
- NIEMALS Key-Werte in Variablen loggen oder in temporäre Dateien schreiben
- NIEMALS `.env`-Dateien für den Anwender erstellen oder bearbeiten (Key könnte im LLM-Kontext exponiert werden)
- NIEMALS Befehle ausführen, die `.env`-Dateien als Ausgabe produzieren könnten (z.B. `find . -name .env`)
- Zum Prüfen ob Key existiert: `python3 scripts/find_api_key.py` (gibt nur "OK" + Länge aus)
- Bei Fehler "Key nicht gefunden": Anwender anweisen, die Umgebungsvariable zu prüfen — NICHT die Datei für ihn anlegen

---

## Schritt 2: Modell auswählen

**Default: `gemini-3.1-flash-image-preview`**

| Wenn der Anwender sagt... | Modell verwenden |
|---|---|
| Nichts Bestimmtes / Standard | **`gemini-3.1-flash-image-preview`** (NB2) |
| "Nano Banana 1", "altes Modell", "2.5" | `gemini-2.5-flash-image` (NB1) |
| "Nano Banana Pro", "Pro", "3 Pro" | `gemini-3-pro-image-preview` (NB Pro) |
| "Imagen", "Imagen 4", "nur Text-zu-Bild" | `imagen-4.0-generate-001` (Imagen 4) |
| "schnellstes", "schnell", "Imagen Fast" | `imagen-4.0-fast-generate-001` |
| "beste Qualität", "Ultra" | `imagen-4.0-ultra-generate-001` |

### Modell-Fähigkeiten im Detail

**Nano Banana 2 (`gemini-3.1-flash-image-preview`)** — Default

- Streaming (`generate_content_stream`) für progressives Rendern
- ThinkingConfig: `thinking_level` = `"minimal"` (Default) oder `"high"`
- Auflösung: `"512"`, `"1K"` (Default), `"2K"`, `"4K"`
- 14 Aspect Ratios inkl. exklusive `"1:4"`, `"4:1"`, `"1:8"`, `"8:1"`
- Referenzbilder: bis zu 10 Objekte + 4 Charaktere = max. 14 Bilder
- Google Web Search + Image Search Grounding (einziges Modell mit Image Search)
- Thinking Tokens werden immer berechnet (unabhängig von `include_thoughts`)
- Output: bis zu 10 Bilder pro Prompt
- Thought Signatures: werden automatisch vom SDK verwaltet in Multi-Turn

**Nano Banana 1 (`gemini-2.5-flash-image`)** — GA/Stable

- Kein `image_size` Parameter (feste ~1024px Auflösung)
- 10 Aspect Ratios (keine extremen Verhältnisse)
- Max. 3 Eingabebilder optimal
- Kein Streaming, kein ThinkingConfig, kein Google Search
- Output: bis zu 10 Bilder pro Prompt
- Günstigstes Gemini-Modell (~$0.039/Bild)

**Nano Banana Pro (`gemini-3-pro-image-preview`)** — Premium

- Thinking immer aktiv (kann nicht deaktiviert werden)
- Auflösung: `"1K"`, `"2K"`, `"4K"` (kein 512)
- Referenzbilder: bis zu 6 Objekte + 5 Charaktere
- Google Web Search (kein Image Search)
- Höchste Textgenauigkeit in Bildern
- C2PA Content Credentials verfügbar

**Imagen 4 (`imagen-4.0-generate-001`)** — Nur Text-zu-Bild

- Separater API-Endpunkt: `client.models.generate_images()`
- 1-4 Bilder pro Request
- Seed für deterministische Reproduktion (erfordert `add_watermark=False`)
- `person_generation`: `"dont_allow"`, `"allow_adult"` (Default), `"allow_all"`
- `safety_filter_level`: `"block_low_and_above"`, `"block_medium_and_above"` (Default), `"block_only_high"`
- Keine Bildbearbeitung, kein Multi-Turn
- Max. Prompt-Länge: 480 Tokens, nur Englisch

---

## Schritt 3: Optimalen Prompt entwickeln

> **Grundprinzip:** "Describe the scene, don't just list keywords."
> Ein narrativer Absatz liefert fast immer ein besseres Bild als eine Stichwortliste.

### Automatische Prompt-Verbesserung

Wenn der Anwender eine kurze Beschreibung gibt, erweitere den Prompt um (sofern sinnvoll):

- **Komposition**: close-up, wide-angle, aerial view, eye-level, 45 elevated
- **Beleuchtung**: golden hour, three-point softbox, rim lighting, diffused natural light
- **Stil**: photorealistic, illustrated, painterly
- **Stimmung**: serene, dramatic, vibrant, nostalgic
- **Technisch**: Objektivtyp, Bokeh, Tiefenschärfe
- **Text im Bild**: Text immer in Anführungszeichen: `the text "The Daily Grind"`
- **Generierungs-Trigger**: Prompt mit "Create an image of..." beginnen verhindert reine Textantworten
- **Semantische Negative**: "an empty deserted street" statt "no cars"

### Prompt-Typen

Detailvorlagen in `references/prompt-strategies.md`. Hier die Übersicht:

**Text-zu-Bild:**

1. Fotorealistische Szenen
2. Stilisierte Illustrationen und Sticker / Icons (3D tactile style)
3. Text im Bild (Logos, Menüs, Infografiken)
4. Produkt-Mockups und kommerzielle Fotografie
5. Minimalistisch und Negativraum
6. Comic und Storyboard (mit Referenzbild)
7. Google Search Grounding (Echtzeit-Daten)

**Bild-zu-Bild (Bildbearbeitung):**

> **Hinweis:** Wenn der Anwender ein Bild inline im Chat teilt (nicht als Dateipfad):
> 1. Zuerst prüfen: Gibt es einen `input/`-Ordner im cwd?
> 2. Genau eine Bilddatei gefunden: automatisch als `--input-image` verwenden
> 3. Mehrere Bilddateien: Anwender die Liste zeigen und fragen
> 4. Kein `input/`-Ordner: nach dem Dateipfad fragen

8. Elemente hinzufügen/entfernen
9. Inpainting (semantisches Maskieren)
10. Style Transfer (Kunststil-Übertragung)
11. Mehrere Bilder kombinieren (Advanced Composition)
12. Detail-Preservation (Gesicht/Logo unverändert lassen)
13. Sketch-to-Life (Skizze zu Foto)
14. Character Consistency (360-Grad-Ansichten)

---

## Schritt 3b: Multi-Referenzbild-Generierung

Wenn der Anwender mehrere Personen oder Szenen als Referenz mitgibt (z.B. "nutze diese Fotos als Vorlage"), verwende die `--character` und `--object` Flags von `generate_image.py` statt ein eigenes Skript zu schreiben.

### Wann Multi-Referenz nutzen

- Anwender liefert Referenzbilder von **Personen**, die im generierten Bild erscheinen sollen → `--character`
- Anwender liefert Referenzbilder von **Orten, Szenen, Objekten** als Vorlage → `--object`
- Anwender will **Character Consistency** (gleiche Person in verschiedenen Szenen)
- Anwender gibt Bilder aus einem `input/`-Ordner oder direkt per Pfad an

### Format der Flags

```
--character "Beschreibung der Person::bild1.jpg,bild2.jpg,bild3.jpg"
--object "Beschreibung der Szene/des Objekts::bild1.jpg,bild2.jpg"
```

Beide Flags sind **wiederholbar** — für jede weitere Person/jedes weitere Objekt ein eigenes Flag.

### Limits pro Modell

| Modell | Max. Charaktere | Max. Objekte | Max. Bilder gesamt |
|---|---|---|---|
| NB2 | 4 | 10 | 14 |
| NB Pro | 5 | 6 | 11 |
| NB1 | — | — | 3 (optimal) |

### Prompt-Strategie bei Multi-Referenz

Der Prompt muss die Referenzbilder mit der gewünschten Szene verbinden. Beschreibe für jeden Charakter:

1. **Welche Referenz-Gruppe** er ist ("Character 1 from the first set of reference photos")
2. **Visuelle Merkmale**, die übernommen werden sollen (Kleidung, Gesichtszüge, Körperbau)
3. **Rolle in der Szene** (Position, Aktion, Ausdruck)

Verwende `thinking_level="high"` — komplexe Multi-Charakter-Kompositionen profitieren stark davon.

**Beispiel — Multi-Reference-Editing:**

Eine Person aus Foto A wird in eine Szene aus Foto B platziert. Beide Referenzen werden als separate Slots übergeben, der Prompt referenziert sie explizit (z.B. „Die Person aus dem ersten Bild steht in der Umgebung aus dem zweiten Bild").

### Wie es intern funktioniert

Das Skript baut beschriftete API-Parts in dieser Reihenfolge auf:

1. **Charakter-Gruppen zuerst** — Text-Label + Bilder pro Charakter (Gesichtstreue hat Priorität)
2. **Objekt-Gruppen danach** — Text-Label + Bilder pro Szene/Objekt
3. **Generierungs-Prompt am Ende** — die eigentliche Szenenbeschreibung

Dieses Label-Pattern ist entscheidend: es hilft dem Modell zu verstehen, welche Bilder zusammengehören und welche Rolle sie in der Komposition spielen.

### Generierungs-Vorschau bei Multi-Referenz

In der Vorschau (Schritt 5) werden Multi-Referenzbilder so angezeigt:

```
  Referenzbilder:  9 Bilder (2 Charaktere + 1 Objekt)
                   Charakter 1: 3 Bilder (Person A, Beschreibung)
                   Charakter 2: 3 Bilder (Person B, Beschreibung)
                   Objekt 1: 3 Bilder (Szene/Venue)
```

---

## Schritt 4: API-Einstellungen konfigurieren

### Intelligente Einstellungs-Empfehlung

Der Skill wählt die optimalen Einstellungen basierend auf dem Anwendungsfall:

| Anwendungsfall | Aspect Ratio | Auflösung | Thinking | Modell | Google Search |
|---|---|---|---|---|---|
| Social Media Post (Instagram) | `4:5` | `1K` | minimal | NB2 | nein |
| Instagram Story / TikTok | `9:16` | `1K` | minimal | NB2 | nein |
| YouTube Thumbnail | `16:9` | `1K` | minimal | NB2 | nein |
| Präsentations-Slide | `16:9` | `2K` | minimal | NB2 | nein |
| Logo / Icon | `1:1` | `1K` | minimal | NB2 | nein |
| Poster / Buchcover | `2:3` | `2K` | high | NB2 | nein |
| Werbebanner (Web) | `16:9` oder `21:9` | `2K` | minimal | NB2 | nein |
| Wallpaper (Desktop) | `16:9` | `4K` | minimal | NB Pro | nein |
| Wallpaper (Mobile) | `9:16` | `2K` | minimal | NB2 | nein |
| Infografik | `2:3` oder `9:16` | `2K` | high | NB2 | nein |
| Infografik mit Echtzeitdaten | `16:9` | `2K` | high | NB2 | Web Search |
| Produkt-Foto (E-Commerce) | `1:1` oder `4:3` | `2K` | minimal | NB2 | nein |
| Print (A4 Portrait) | `3:4` | `4K` | minimal | NB Pro | nein |
| Cinematic / Film | `21:9` | `4K` | high | NB Pro | nein |
| Schnelle Vorschau / Sketch | `1:1` | `512` | minimal | NB2 | nein |
| Sticker / Emoji | `1:1` | `512` | minimal | NB2 | nein |
| Wetter-/Sport-/News-Grafik | `16:9` | `1K` | minimal | NB2 | Web Search |
| Realistische Tier-/Pflanzen-Darstellung | `3:2` | `2K` | high | NB2 | Image Search |

### Aspect Ratio — Vollständige Liste

| Ratio | Wann nutzen | NB1 | NB2 | NB Pro |
|---|---|---|---|---|
| `1:1` | Logos, Icons, Social Posts | ja | ja | ja |
| `9:16` | Stories, Mobile Wallpaper | ja | ja | ja |
| `16:9` | Präsentationen, YouTube, Banner | ja | ja | ja |
| `2:3` | Buchcover, Poster, Pinterest | ja | ja | ja |
| `3:2` | Querformat Foto, Landschaft | ja | ja | ja |
| `3:4` | Portrait-Foto | ja | ja | ja |
| `4:3` | Klassisches Foto | ja | ja | ja |
| `4:5` | Instagram Feed | ja | ja | ja |
| `5:4` | Breiteres Portrait | ja | ja | ja |
| `21:9` | Cinematic, Header, Widescreen | ja | ja | ja |
| `1:4` | Extrem hochkant, Sidebar | nein | ja | nein |
| `4:1` | Extrem breit, Panorama | nein | ja | nein |
| `1:8` | Ultra-hochkant | nein | ja | nein |
| `8:1` | Ultra-breit | nein | ja | nein |

### Auflösung (image_size)

| Setting | NB1 | NB2 | NB Pro | Imagen 4 |
|---|---|---|---|---|
| `"512"` (0.5K) | nein | ja | nein | nein |
| `"1K"` (Default) | nein (kein Param) | ja | ja | ja |
| `"2K"` | nein | ja | ja | ja (Ultra) |
| `"4K"` | nein | ja | ja | nein |

**Großes K zwingend!** `"1K"`, `"2K"`, `"4K"` — Kleinbuchstaben `"1k"` werden abgelehnt.
**Ausnahme:** `"512"` hat kein K-Suffix.

### ThinkingConfig (nur Nano Banana 2)

```python
thinking_config=types.ThinkingConfig(
    thinking_level="minimal",   # "minimal" (niedrigste Latenz) oder "high"
    include_thoughts=True        # optional: Denkprozess sichtbar machen
)
```

- Thinking-Tokens werden IMMER berechnet (auch wenn `include_thoughts=False`)
- `"minimal"` für Standard, `"high"` für komplexe Kompositionen, Infografiken, Comic-Panels, präzise Text-Layouts

### Google Search Tool

**Web Search** (NB2 und NB Pro):

```python
tools=[{"google_search": {}}]
```

**Image Search** (nur NB2, exklusiv):

```python
tools=[types.Tool(google_search=types.GoogleSearch(
    search_types=types.SearchTypes(
        web_search=types.WebSearch(),
        image_search=types.ImageSearch()
    )
))]
```

Wann Google Search aktivieren:

- Anwender fragt nach aktuellen Daten (Wetter, Sport, Nachrichten, Börsenkurse)
- Anwender möchte reale Orte/Landmarks korrekt dargestellt haben
- Anwender möchte spezifische Tier-/Pflanzenarten realistisch abbilden (→ Image Search)
- Anwender erwähnt "aktuell", "heute", "gestern", "neueste"

Pflicht bei Image Search: Quellen-Attribution mit Link zur Quellwebseite anzeigen.
NB2 Image Search verwendet keine echten Personenfotos aus der Websuche.

### Response Modalities

- `["TEXT", "IMAGE"]` — Text-Kommentar + Bild (Standard)
- `["IMAGE"]` — nur Bild, kein begleitender Text

### Transparenter Hintergrund (Chroma-Key zu Alpha-Kanal)

**NUR verwenden, wenn der Anwender EXPLIZIT Transparenz anfordert.**
Trigger-Wörter: "transparenter Hintergrund", "transparent background", "PNG transparent", "freistellen", "ohne Hintergrund", "no background", "Alpha-Kanal", "Hintergrund entfernen".
**NICHT automatisch bei Logos, Icons oder Stickern verwenden!**

Gemini kann keine echten Alpha-Channel-PNGs erzeugen. Mit `--transparent-bg` (`-t`) wird:

1. Der Prompt um Chroma-Key-Hintergrund-Anweisung erweitert
2. Das Bild generiert
3. Auto-Detection der tatsächlichen Hintergrundfarbe aus den 4 Ecken
4. Automatische Korrektur, falls Modell andere Farbe als angefordert verwendet
5. Einfarbiger Hintergrund durch Transparenz ersetzt

| Parameter | Kurz | Standard | Beschreibung |
|---|---|---|---|
| `--transparent-bg` | `-t` | `false` | Transparenz-Modus aktivieren |
| `--bg-key-color` | — | `#FF00FF` | Chroma-Key Farbe (Hex) |
| `--bg-tolerance` | — | `60` | Farbdistanz-Schwellwert (0-255) |

---

## Schritt 5: Bestätigung einholen — PFLICHT VOR JEDER GENERIERUNG

> **Kernregel:** Vor JEDER Bildgenerierung müssen ALLE Einstellungen dem Anwender gezeigt und seine Bestätigung eingeholt werden. Erst nach positivem OK wird generiert.

### Ablauf

1. Sammle alle Einstellungen basierend auf dem Anwender-Wunsch
2. Zeige dem Anwender eine **Generierungs-Vorschau** im folgenden Format:

```
Generierungs-Vorschau:

  Prompt:        "Der optimierte Prompt in voller Länge"
  Modell:         Nano Banana 2 (gemini-3.1-flash-image-preview)
  Seitenverh.:    16:9
  Auflösung:      2K
  Thinking:       high
  Google Search:  Web Search aktiv
  Eingabebild:    [keins / Pfad zum Bild]
  Referenzbilder: [keins / Anzahl + Aufschlüsselung nach Charakter/Objekt]
  Transparenz:    nein
  Ausgabepfad:    assets/generated_images/dateiname.png
  Gesch. Kosten:  ~$0.10 (1 Bild, NB2 2K)

Soll ich mit diesen Einstellungen generieren, oder möchtest du etwas ändern?
```

### Preisschätzung berechnen

Die geschätzten Kosten MÜSSEN in der Vorschau angezeigt werden. Berechnung:

| Modell | 512 | 1K | 2K | 4K |
|---|---|---|---|---|
| NB1 | — | ~$0.039 | — | — |
| NB2 | ~$0.045 | ~$0.067 | ~$0.101 | ~$0.151 |
| NB Pro | — | ~$0.134 | ~$0.134 | ~$0.24 |
| Imagen 4 Fast | — | $0.02 | — | — |
| Imagen 4 Standard | — | $0.04 | — | — |
| Imagen 4 Ultra | — | $0.06 | — | — |

Hinweise zur Berechnung:

- Bei NB2/NB Pro kommen ggf. Text-Input-Token-Kosten hinzu (~$0.001-0.005, vernachlässigbar)
- Thinking-Tokens (NB2 high): zusätzlich ~$0.01-0.03 (variiert stark)
- Google Search: keine separaten Kosten für die Suche selbst
- Batch API: 50% Rabatt auf obige Preise
- Format: `~$X.XX (Anzahl Bilder, Modell, Auflösung)`

3. **Warte auf die Antwort des Anwenders:**
   - Anwender sagt "ja", "passt", "ok", "los", "generiere", "mach" → Weiter zu Schritt 6
   - Anwender sagt "ändern", korrigiert Werte, gibt Feedback → Einstellungen anpassen, neue Vorschau zeigen
   - Anwender sagt "direkt generieren" / "ohne Nachfrage" → Ausnahme: sofort generieren

### Ausnahmen (keine Bestätigung nötig)

- Anwender hat explizit gesagt: "direkt generieren", "ohne Nachfrage", "einfach machen"
- Anwender wiederholt denselben Auftrag mit minimaler Änderung (z.B. "nochmal, aber in blau")
- Multi-Turn Iteration: Anwender verfeinert ein bereits generiertes Bild ("mach den Hintergrund heller")

### Was IMMER gezeigt werden muss

| Feld | Immer zeigen | Nur wenn relevant |
|---|---|---|
| Prompt (optimiert) | ja | — |
| Modell + ID | ja | — |
| Aspect Ratio | ja | — |
| Auflösung | ja | — |
| Thinking Level | — | nur NB2 |
| Google Search | — | nur wenn aktiv |
| Eingabebild | — | nur bei Bildbearbeitung |
| Referenzbilder | — | nur bei Multi-Referenz (Anzahl + Aufschlüsselung) |
| Transparenz | — | nur wenn aktiv |
| Ausgabepfad | ja | — |

---

## Schritt 6: API-Aufruf ausführen

### Ausgabepfad

Generierte Bilder IMMER im Projektordner speichern:
`--output {projekt_root}/assets/generated_images/{dateiname}.png`

Verwende IMMER `--output` mit dem vollständigen Pfad zum Projektordner des Anwenders.

Nutze `scripts/generate_image.py`. **Default ist Nano Banana 2.**

```bash
# Standard (Nano Banana 2)
python3 scripts/generate_image.py --prompt "Dein Prompt" --aspect-ratio 16:9

# Mit Auflösung
python3 scripts/generate_image.py --prompt "Dein Prompt" --resolution 2K --aspect-ratio 16:9

# Mit High-Thinking für komplexe Szenen
python3 scripts/generate_image.py --prompt "Komplexe Komposition" --thinking-level high

# Nano Banana 1 (explizit)
python3 scripts/generate_image.py --prompt "Dein Prompt" --model gemini-2.5-flash-image

# Nano Banana Pro mit Google Search
python3 scripts/generate_image.py --prompt "Heutiges Wetter Berlin" \
  --model gemini-3-pro-image-preview --google-search --aspect-ratio 16:9

# Nano Banana 2 mit Google Search (Web + Image)
python3 scripts/generate_image.py --prompt "Realistischer Quetzal-Vogel als Wallpaper" \
  --google-search --aspect-ratio 3:2 --resolution 2K

# Bildbearbeitung
python3 scripts/generate_image.py --prompt "Hintergrund weiß machen" \
  --input-image mein_foto.jpg --output bearbeitet.png

# Transparenter Hintergrund
python3 scripts/generate_image.py --prompt "Flat vector coffee logo" -t --aspect-ratio 1:1

# Multi-Referenzbild: Charaktere + Szene (siehe Schritt 3b für Details)
python3 scripts/generate_image.py --prompt "Both characters on stage performing" \
  --character "Person in dark suit::input/p1_a.jpg,input/p1_b.jpg" \
  --character "Person in light blazer::input/p2_a.jpg,input/p2_b.jpg" \
  --object "Concert venue::input/venue1.jpg,input/venue2.jpg" \
  --aspect-ratio 16:9 --resolution 2K --thinking-level high
```

---

## Schritt 7: Ergebnis präsentieren

1. Bild mit `present_files` anzeigen (wenn verfügbar)
2. Verwendeten Prompt kurz nennen
3. Anbieten zu verfeinern: Stil, Seitenverhältnis, Details, Thinking-Level erhöhen

### Aufräumen

- Keine temporären Skripte im Projektordner hinterlassen
- Bevorzuge eingebaute Funktionen von `generate_image.py` statt eigene Skripte

---

## Output-Schema

Die interne Wrapper-Funktion `generate_image(prompt, ...)` in `scripts/generate_image.py` gibt ein Dict mit vier Pflicht-Schlüsseln zurück:

```python
{
    "path": Path,                  # Absoluter Pfad zur erzeugten Bild-Datei
    "format": str,                 # "png" | "webp" | "jpeg"
    "size": tuple[int, int],       # (Breite, Höhe) in Pixeln
    "prompt_hash": str,            # SHA-256 hex des verwendeten Prompts
}
```

Konsumenten-Skills (z.B. Composer-Skills, die Bilder weiterverarbeiten) können sich auf diese vier Felder verlassen. Optionale Zusatz-Schlüssel sind erlaubt, dürfen aber die vier Pflicht-Schlüssel nicht überschreiben.

Feature-Flag-Konfiguration (siehe `skill.config.example.yaml`):

- `api_key_env_var` — Name der Umgebungsvariablen mit dem API-Key (Default `GEMINI_API_KEY`)
- `api_timeout_seconds` — Timeout pro API-Aufruf (Default 60)
- `api_max_retries` — Anzahl Retries bei transienten Fehlern (Default 3)

---

## Beratungs-Modus: API-Wissen

Wenn der Anwender Fragen stellt, nutze folgende Quellen für die Antwort:

### Häufige Fragen — Schnellantworten

**"Was kostet die Bildgenerierung?"**

- NB1 (`gemini-2.5-flash-image`): ~$0.039/Bild (1.290 Output-Tokens × $30/1M)
- NB2 (`gemini-3.1-flash-image-preview`): ~$0.045 (512) bis ~$0.151 (4K)/Bild
- NB Pro (`gemini-3-pro-image-preview`): ~$0.134 (1K-2K) bis ~$0.24 (4K)/Bild
- Imagen 4 Standard: $0.04/Bild
- Imagen 4 Ultra: $0.06/Bild
- Imagen 4 Fast: $0.02/Bild
- Batch API (NB2, NB Pro, Imagen 4): 50% Rabatt

**"Kann ich transparente PNGs erzeugen?"**

Kein Modell unterstützt native Transparenz/Alpha-Kanal. Workaround: Chroma-Key-Hintergrund generieren und nachträglich durch Alpha ersetzen (in `generate_image.py` eingebaut via `-t` Flag).

**"Was ist SynthID?"**

Unsichtbares Pixel-Level-Wasserzeichen, das in ALLE generierten Bilder eingebettet wird. Überlebt Kompression, Resize, Crop. Kann nicht deaktiviert werden bei Gemini-Modellen. Bei Imagen: `add_watermark=False` möglich, aber dann kein Seed-Support.

**"Unterschied Gemini vs Imagen?"**

- Gemini (`generate_content`): Multimodal, Multi-Turn, Bildbearbeitung, Text+Bild, Streaming
- Imagen (`generate_images`): Nur Text-zu-Bild, dafür Seed, Safety-Filter, Batch, günstiger

**"Rate Limits?"**

Imagen 3: 20 RPM. Imagen 3 Fast: 200 RPM. Gemini-Modelle: variiert nach Tier.

**"Welche Sprachen werden unterstützt?"**

Beste Ergebnisse: EN. Gut unterstützt: DE, FR, ES, JA, KO, ZH, PT, RU, AR, ID, IT, HI, VI, UA. Imagen 4: nur EN.

**"Was sind Thought Signatures?"**

Verschlüsselte Repräsentationen des Denkprozesses bei Gemini 3 Modellen. Werden automatisch vom SDK in Multi-Turn verwaltet. Wenn man die rohe API nutzt, müssen sie zwischen Turns zurückgegeben werden, sonst kann die Antwort fehlschlagen.

**"Batch API?"**

Für Massenproduktion: höhere Rate Limits, 50% günstigere Preise, Turnaround bis 24 Stunden. Tipp: Bei NB2 mit 512px generieren, dann die besten Ergebnisse in höherer Auflösung neu generieren.

Für detailliertere Fragen: Lade `references/api-reference.md` für die vollständige technische Referenz.

---

## Einschränkungen (offiziell dokumentiert)

- Alle generierten Bilder enthalten ein **SynthID-Wasserzeichen** (unsichtbar, nicht deaktivierbar bei Gemini)
- **Keine native Transparenz** (Alpha-Kanal) bei keinem Modell
- **Keine Audio-/Video-Eingaben** für Bildgenerierung
- Das Modell folgt nicht immer der exakten Anzahl gewünschter Ausgabebilder
- NB1: funktioniert am besten mit max. 3 Eingabebildern
- NB2: max. 4 Charaktere + 10 Objekte als Referenz
- NB2 Image Search: verwendet keine echten Personenfotos aus der Websuche
- Zuerst Text generieren, dann Bild mit Text anfragen (bessere Text-Rendering-Qualität)
- Imagen 4: Max. Prompt-Länge 480 Tokens, nur Englisch, keine Bildbearbeitung
- `image_size` muss Großbuchstaben-K verwenden: `"1K"`, `"2K"`, `"4K"` (nicht `"1k"`)
- Content Policy: keine sexuellen, gewaltverherrlichenden oder rechtsverletzenden Inhalte
- `person_generation="allow_all"` in EU, UK, Schweiz, MENA eingeschränkt (nur Imagen)

---

## Referenzen

- Detaillierte Prompt-Strategien + Vorlagen: `references/prompt-strategies.md`
- Vollständige API-Referenz (Parameter, Preise, Rate Limits): `references/api-reference.md`
- Offizielle API-Doku: https://ai.google.dev/gemini-api/docs/image-generation
- Imagen API-Doku: https://ai.google.dev/gemini-api/docs/imagen
