# Google Gemini Image Generation API — Vollständige Referenz

Technische Referenz für alle Parameter, Modelle, Preise und Limits.
Wird vom Beratungs-Modus des Skills geladen, wenn der Anwender detaillierte API-Fragen stellt.

---

## Inhaltsverzeichnis

1. [Modelle und Status](#1-modelle-und-status)
2. [Gemini Native Image Generation Parameter](#2-gemini-native-parameter)
3. [Imagen API Parameter](#3-imagen-api-parameter)
4. [Preise](#4-preise)
5. [Rate Limits](#5-rate-limits)
6. [Safety Settings](#6-safety-settings)
7. [SynthID und C2PA](#7-synthid-und-c2pa)
8. [Transparenz / Alpha-Kanal](#8-transparenz)
9. [Eingabe-/Ausgabeformate](#9-formate)
10. [Multi-Turn Editing](#10-multi-turn)
11. [Code-Beispiele](#11-code-beispiele)
12. [Fehlerbehandlung](#12-fehlerbehandlung)

---

## 1. Modelle und Status

### Gemini Native Image Generation (via `generate_content`)

| Modell-ID | Status | Nickname |
|---|---|---|
| `gemini-2.0-flash-exp` | Deprecated | — |
| `gemini-2.0-flash-preview-image-generation` | Deprecated (Shutdown 01.06.2026) | — |
| `gemini-2.5-flash-image` | **GA** (seit 02.10.2025) | Nano Banana 1 |
| `gemini-3-pro-image-preview` | Preview | Nano Banana Pro |
| `gemini-3.1-flash-image-preview` | Preview (seit 26.02.2026) | Nano Banana 2 |

### Imagen (via `generate_images`)

| Modell-ID | Status | Beschreibung |
|---|---|---|
| `imagen-3.0-generate-001` | Available | Imagen 3 v1 |
| `imagen-3.0-generate-002` | Available | Imagen 3 v2, Prompt Enhancement |
| `imagen-3.0-fast-generate-001` | Available | Schneller, niedrigere Qualität |
| `imagen-3.0-capability-001` | Available | Inpainting/Outpainting (nur Vertex AI) |
| `imagen-4.0-generate-001` | **GA** (seit Aug 2025) | Standard |
| `imagen-4.0-ultra-generate-001` | **GA** | Höchste Qualität |
| `imagen-4.0-fast-generate-001` | **GA** | Schnellste |

---

## 2. Gemini Native Parameter

### GenerateContentConfig

| Parameter | Typ | Werte | Pflicht |
|---|---|---|---|
| `response_modalities` | list[str] | `["TEXT", "IMAGE"]`, `["IMAGE"]`, `["TEXT"]` | Ja |
| `image_config` | ImageConfig | Siehe unten | Nein |
| `thinking_config` | ThinkingConfig | Siehe unten | Nein (nur NB2) |
| `tools` | list | Google Search config (NB2, NB Pro) | Nein |

### ImageConfig

| Parameter | Typ | Werte | Default | Modelle |
|---|---|---|---|---|
| `aspect_ratio` | str | `"1:1"`, `"3:2"`, `"2:3"`, `"3:4"`, `"4:3"`, `"4:5"`, `"5:4"`, `"9:16"`, `"16:9"`, `"21:9"`, `"1:4"`, `"4:1"`, `"1:8"`, `"8:1"` | `"1:1"` | Alle (1:4/4:1/1:8/8:1 nur NB2) |
| `image_size` | str | `"512"`, `"1K"`, `"2K"`, `"4K"` | `"1K"` | NB2, NB Pro (NB1: kein Param) |

**Wichtig:** `image_size` MUSS Großbuchstaben-K verwenden. `"1k"` wird abgelehnt.
**Ausnahme:** `"512"` hat kein K-Suffix. Nur NB2.

### ThinkingConfig (nur NB2)

| Parameter | Typ | Werte | Default |
|---|---|---|---|
| `thinking_level` | str | `"minimal"`, `"high"` | `"minimal"` |
| `include_thoughts` | bool | `true`/`false` | `false` |

Thinking-Tokens werden IMMER berechnet, auch wenn `include_thoughts=false`.

### Google Search Tools (NB2 und NB Pro)

Beide Gemini 3 Modelle unterstützen Google Search Grounding via `tools=[{"google_search": {}}]`.

**Web Search (Standard):**

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

Grounded Text-Ergebnisse werden genutzt, um Bilder mit Echtzeitdaten zu generieren (Wetter, Nachrichten, Sportergebnisse etc.).

**Image Search (nur NB2):**

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

NB2 kann zusätzlich Google Image Search nutzen, um visuelle Referenzen für die Generierung zu finden (z.B. Tierarten, Landmarken, Pflanzen). Image Search kann allein oder zusammen mit Web Search genutzt werden.

**Einschränkungen Image Search:**

- Keine Personenbilder aus der Websuche
- `response_modalities` muss `["IMAGE"]` enthalten
- Grounding-Metadaten enthalten `imageSearchQueries`, `groundingChunks` (mit `uri` und `image_uri`), und `searchEntryPoint`

**Display-Pflichten bei Image Search:**

- Source Attribution: Link zur Quellseite (nicht zur Bilddatei direkt)
- Direct Navigation: Ein-Klick-Pfad vom Quellbild zur Quellwebseite

### Context Window

| Modell | Max Input Tokens | Max Output Tokens | Tokens pro Bild |
|---|---|---|---|
| NB1 (`gemini-2.5-flash-image`) | 32.768 | 32.768 | ~1.290 |
| NB2 (`gemini-3.1-flash-image-preview`) | 32.768 | 32.768 | variiert nach Auflösung |
| NB Pro (`gemini-3-pro-image-preview`) | 32.768 | 32.768 | variiert nach Auflösung |

### Max Eingabebilder

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

### Max Ausgabebilder pro Prompt

| Modell | Max |
|---|---|
| NB1 | 10 |
| NB2 | 10 |
| NB Pro | variiert |
| Imagen 4 | 4 |

### Max Dateigröße

- Inline: 7 MB
- Cloud Storage: 30 MB

---

## 3. Imagen API Parameter

### GenerateImagesConfig

| Parameter | Typ | Werte | Default | Hinweise |
|---|---|---|---|---|
| `number_of_images` | int | 1-4 | variiert | Bilder pro Request |
| `aspect_ratio` | str | `"1:1"`, `"3:4"`, `"4:3"`, `"9:16"`, `"16:9"` | `"1:1"` | Weniger als Gemini |
| `image_size` | str | `"1K"`, `"2K"` | `"1K"` | Standard/Ultra |
| `person_generation` | str | `"dont_allow"`, `"allow_adult"`, `"allow_all"` | `"allow_adult"` | `allow_all` in EU eingeschränkt |
| `safety_filter_level` | str | `"block_low_and_above"`, `"block_medium_and_above"`, `"block_only_high"`, `"block_none"` | `"block_medium_and_above"` | |
| `negative_prompt` | str | beliebig | — | NUR Imagen 3 v1, ab v2 entfernt |
| `add_watermark` | bool | true/false | true | false: kein SynthID, ermöglicht Seed |
| `seed` | uint32 | 1-2.147.483.647 | — | Erfordert `add_watermark=false` |
| `language` | str | `"en"`, `"auto"`, `"zh"`, `"hi"`, `"ja"`, `"ko"`, `"pt"`, `"es"` | `"en"` | |
| `enhance_prompt` | bool | true/false | true | LLM-basiertes Prompt-Rewriting |
| `output_mime_type` | str | `"image/png"`, `"image/jpeg"` | `"image/png"` | |
| `compression_quality` | int | 0-100 | 75 | Nur JPEG |
| `include_rai_reason` | bool | true/false | false | Safety-Filter-Gründe anzeigen |

### Imagen Einschränkungen

- `seed` und `add_watermark=true` sind inkompatibel
- `enhance_prompt=true` macht `seed` unwirksam
- `negative_prompt` ab `imagen-3.0-generate-002` nicht mehr unterstützt
- Max. Prompt-Länge: 480 Tokens
- Imagen 4: nur Englisch

### Imagen Ausgabe-Auflösungen (Imagen 3)

| Aspect Ratio | Pixel |
|---|---|
| 1:1 | 1024x1024 |
| 3:4 | 896x1280 |
| 4:3 | 1280x896 |
| 9:16 | 768x1408 |
| 16:9 | 1408x768 |

---

## 4. Preise

### Gemini Native Image Generation

| Modell | Pro Bild | Batch (50% Rabatt) |
|---|---|---|
| NB1 (`gemini-2.5-flash-image`) | ~$0.039 | ~$0.0195 |
| NB2 0.5K | ~$0.045 | ~$0.023 |
| NB2 1K | ~$0.067 | ~$0.034 |
| NB2 2K | ~$0.101 | ~$0.051 |
| NB2 4K | ~$0.151 | ~$0.076 |
| NB Pro 1K-2K | ~$0.134 | ~$0.067 |
| NB Pro 4K | ~$0.24 | ~$0.12 |

Text-Tokens (Gemini 2.5 Flash): $0.30/1M Input, $2.50/1M Output

### Imagen

| Modell | Pro Bild |
|---|---|
| Imagen 4 Fast | $0.02 |
| Imagen 4 Standard | $0.04 |
| Imagen 4 Ultra | $0.06 |
| Imagen 3 v2 | $0.03 |

---

## 5. Rate Limits

| Modell | Requests/Minute |
|---|---|
| Imagen 3 Standard | 20 RPM |
| Imagen 3 Fast | 200 RPM |
| Imagen 3 Capability | 100 RPM |
| Gemini-Modelle | Variiert nach Tier |

---

## 6. Safety Settings

### Gemini Native

Standard Gemini Safety Settings via `safetySettings` im Request. Kein separater Image-Safety-Filter auf Gemini API Level.

### Imagen

**`safety_filter_level`:**

- `"block_low_and_above"` — Restriktivste: blockt auch geringe Wahrscheinlichkeit
- `"block_medium_and_above"` — Default
- `"block_only_high"` — Nur hohe Konfidenz
- `"block_none"` — Kein Blocking (nur in Allowlisted Use Cases)

**`person_generation`:**

- `"dont_allow"` — Keine Personen/Gesichter
- `"allow_adult"` — Erwachsene und Prominente (Default)
- `"allow_all"` — Erwachsene und Kinder; **eingeschränkt in EU, UK, Schweiz, MENA**

---

## 7. SynthID und C2PA

### SynthID

- Unsichtbares Pixel-Level-Wasserzeichen
- In ALLE generierten Bilder eingebettet (bei Gemini nicht deaktivierbar)
- Überlebt Kompression, Resize, Crop, Re-Encoding
- Extrem aggressive Modifikationen können es degradieren
- Bei Imagen: `add_watermark=false` möglich

### C2PA Content Credentials

- Tamper-evident signierter Nachweis der KI-Herkunft
- Verfügbar bei: NB Pro, Imagen 4 (Vertex AI)
- Wird entfernt bei: Screenshots, Plattformen, die EXIF strippen, Metadata-Removal-Tools

### Verifikation

Anwender können Bilder in der Gemini App hochladen und fragen, ob sie KI-generiert sind.

---

## 8. Transparenz

**Status: Von keinem aktuellen Modell nativ unterstützt.**

Kein Gemini- oder Imagen-Modell kann echte transparente PNGs (mit Alpha-Kanal) erzeugen.
"Transparent background" im Prompt erzeugt einen soliden Hintergrund, nicht Transparenz.

**Workarounds:**

1. Chroma-Key: Magenta/Grün-Hintergrund generieren, dann per HSV-Detection entfernen (eingebaut in `generate_image.py` via `-t`)
2. Background-Removal-Modell (z.B. `rembg`) nachschalten
3. OpenCV/PIL Post-Processing als BGRA-Konvertierung

---

## 9. Formate

### Eingabe-Formate

PNG, JPEG, WebP, HEIC, HEIF

### Ausgabe-Formate

| | Gemini Native | Imagen |
|---|---|---|
| Encoding | `inline_data` (base64) | `bytesBase64Encoded` |
| Default MIME | `image/png` | `image/png` |
| JPEG | nicht konfigurierbar | `output_mime_type="image/jpeg"` |
| JPEG-Qualität | — | `compression_quality` 0-100 |
| Cloud Storage | Nein (Gemini API) | Ja (Vertex AI) |

---

## 10. Multi-Turn Editing

Nur Gemini Native (NB1, NB2, NB Pro). Nicht mit Imagen.

```python
chat = client.chats.create(
    model="gemini-2.5-flash-image",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    )
)
response = chat.send_message("Generate an image of a red sports car")
response2 = chat.send_message("Now add snow falling around the car")
```

- Jede Nachricht kann vorherige Bilder referenzieren
- Character Consistency bleibt über Turns erhalten
- Bei langem Multi-Turn kann Drift auftreten (Fix: Neustart mit detaillierter Beschreibung)
- Aspect Ratio und Resolution können pro Turn geändert werden
- NB Pro: Thought Signatures werden automatisch vom SDK verwaltet

---

## 11. Code-Beispiele

### Text-zu-Bild (Gemini Native)

```python
from google import genai
from google.genai import types

client = genai.Client(api_key="GEMINI_API_KEY")

response = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents="A cartoon infographic for flying sneakers",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="9:16",
        ),
    ),
)

for part in response.parts:
    if part.inline_data:
        generated_image = part.as_image()
        generated_image.show()
```

### Text-zu-Bild (Imagen 4)

```python
response = client.models.generate_images(
    model="imagen-4.0-generate-001",
    prompt="Robot holding a red skateboard",
    config=types.GenerateImagesConfig(
        number_of_images=4,
    )
)
for generated_image in response.generated_images:
    generated_image.image.show()
```

### Bildbearbeitung (Gemini Native)

```python
import PIL.Image

input_image = PIL.Image.open("my_photo.jpg")
response = client.models.generate_content(
    model="gemini-2.5-flash-image",
    contents=[input_image, "Change the background to a tropical beach"],
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
    ),
)
```

### Mit Seed (Imagen, deterministisch)

```python
response = client.models.generate_images(
    model="imagen-3.0-generate-001",
    prompt="A portrait of a sheepadoodle",
    config=types.GenerateImagesConfig(
        number_of_images=1,
        add_watermark=False,
        seed=12345,
    )
)
```

### NB2 Streaming

```python
for chunk in client.models.generate_content_stream(
    model="gemini-3.1-flash-image-preview",
    contents=contents,
    config=gen_config
):
    if chunk.parts:
        for part in chunk.parts:
            if part.inline_data:
                # Bild progressiv empfangen
                pass
```

---

## 12. Fehlerbehandlung

| Fehler | Ursache | Lösung |
|---|---|---|
| `image_size` rejected | Kleinbuchstaben verwendet | `"1K"` statt `"1k"` verwenden |
| Kein Bild in Response | Safety-Filter oder Prompt zu vage | Prompt spezifischer machen, Safety prüfen |
| 429 Too Many Requests | Rate Limit erreicht | Warten und retry, oder Batch API nutzen |
| `seed` + `add_watermark` Fehler | Inkompatible Kombination | `add_watermark=False` setzen für Seed |
| `negative_prompt` ignored | Imagen v2+ | Feature entfernt, semantische Negation im Prompt nutzen |
| Bild zeigt falschen Hintergrund bei -t | Modell folgt Farbanweisung nicht | Auto-Detection korrigiert automatisch |
| Content blocked | Policy-Verstoß | Prompt anpassen, keine verbotenen Inhalte |
| `allow_all` rejected | Region eingeschränkt | `"allow_adult"` in EU/UK/CH/MENA verwenden |
