---
type: skill
name: openai-image-gen
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:
  - openai-image
  - gpt-image
  - gpt-image-2
  - dall-e
  - openai-bild
  - image-generation
created: 2026-05-19
updated: 2026-05-19
description: "Wrapper für die OpenAI gpt-image-2 API. Erzeugt Bilder aus Text-Prompts, unterstützt Multi-Reference-Editing, Inpainting, Output-Format-Steuerung (PNG/WebP, transparent), input_fidelity-Parameter (außer bei gpt-image-2-Modell). Liest OPENAI_API_KEY aus der Umgebung (per Skill-Config überschreibbar). Empfohlene Setup-Methode: 1Password CLI mit op-run.sh-Wrapper."
---

# OpenAI Image Generation Skill

Als Sub-Skill von `authentic-portrait` und `linkedin-finalize` übernimmt er die eigentlichen API-Aufrufe gegen gpt-image-2. Für direkte Aufrufe gilt: `input_fidelity` ist bei gpt-image-2 nicht unterstützt (400-Fehler), kein API-Key landet in Logs oder LLM-Kontext, und generiert wird erst nach Bestätigung eines explizit gezeigten Generierungsplans.

## ⛔ 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.

## Voraussetzungen

- Python 3.11+ und die Library aus `requirements.txt`
- Umgebungsvariable mit dem API-Key (Default-Name: `OPENAI_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.

### API Key Setup

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

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

Im Python-Skript: `os.environ.get("OPENAI_API_KEY")` verwenden. Der Wert darf nicht geloggt, gedruckt oder in den LLM-Kontext zurückfließen.

```python
import os

api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise SystemExit("OPENAI_API_KEY nicht gesetzt. Siehe INSTALL.md für Setup-Optionen.")
```

---

## Modus-Entscheidung: Advise, Optimize oder Generate?

Vor jeder Antwort prüfen, was der Anwender wirklich braucht:

### 1. Advisor Mode — Frage beantworten (kein Code, kein Bild)

Wenn der Anwender nach API-Details fragt: Pricing, Parameter, Best Practices, Troubleshooting, Modell-Unterschiede, Funktionsweise. Beispiele:

- "Was kostet ein Bild mit gpt-image-1.5?"
- "Welches Modell soll ich nehmen?"
- "Was ist der Unterschied zwischen quality high und medium?"
- "Wie funktioniert Inpainting?"
- "Welche Formate unterstützt die API?"

Antworte direkt aus den Referenzdateien. Keine Skript-Generierung nötig. Sei präzise und gründlich.

### 2. Prompt Optimization Mode — Prompt schärfen (noch kein Bild)

Wenn der Anwender einen Prompt entwickeln oder verbessern möchte ohne sofortige Bildgenerierung. Beispiele:

- "Hilf mir einen guten Prompt zu schreiben für..."
- "Wie würdest du diesen Prompt verbessern?"
- "Optimiere meinen Prompt"

Nutze die Prompt-Engineering-Konventionen, erkläre die Wahl. Generiere kein Bild ohne explizite Aufforderung.

### 3. Generation Mode — Bild erzeugen

Wenn ein konkretes Bild verlangt wird. Beispiele:

- "Erstelle mir ein Logo für..."
- "Generate an image of..."
- "Bearbeite dieses Bild..."
- "Mach den Hintergrund transparent"

Folge dem **Confirmation Workflow** unten. Niemals direkt generieren — erst den Plan zeigen.

---

## Generation Mode: Confirmation Workflow

Ziel: Anwender sieht vor dem API-Call, was passiert und was es kostet.

### Schritt 1: Anfrage analysieren

Was für ein Bild? (Foto, Illustration, Logo, Icon, Mockup, Edit, Inpainting) — welche Qualität? — welches Format? — Sonderanforderungen (Transparenz, Text, Gesichter, Brand)?

### Schritt 2: Prompt optimieren

Verwandle die Beschreibung in einen produktionsreifen Prompt. Best-Practice-Reihenfolge:

```
[Scene/Environment] + [Subject/Main element] + [Key details: materials, textures, lighting] + [Style/Medium] + [Composition/Perspective] + [Constraints/Exclusions]
```

Kernregeln:
- Prompts in **Englisch** schreiben für beste Ergebnisse (auch wenn Anwender Deutsch spricht)
- Konkret und spezifisch, vage Begriffe durch präzise Beschreibungen ersetzen
- Photographische Hinweise für Realismus (Linse, Blende, Kamera, Lichtquelle)
- Literaler Text in Anführungszeichen: `A label reading "Bio Kaffee"`
- Bei schwierigen Wörtern Buchstabe für Buchstabe: `"O-P-E-N-A-I"`
- Negativ-Constraints einsetzen: `no text, no watermarks, clean background`
- Bei text-lastigen Bildern immer `quality="high"`

Mehr Prompt-Muster: `references/prompt-guide.md` und `references/prompt-patterns.md`.

### Schritt 3: Parameter wählen

**Modell-Auswahl:**

| Modell | Stärken | Speed | Kosten |
|---|---|---|---|
| `gpt-image-2` | **Default** — bestes Text-Rendering (mehrsprachig), Infografiken, Layouts, Photorealismus, Multi-Reference-Komposition, bis 2000 px Breite, bis zu 10 Bilder pro Call. Snapshot-ID: `gpt-image-2-2026-04-21` | Moderat | Quality-first, höher als 1.5 |
| `gpt-image-1.5` | Solide Allzweck-Wahl wenn Kosten/Speed wichtig | 4x schneller als gpt-image-1 | ~20% günstiger als gpt-image-1 |
| `gpt-image-1` | Legacy, Premium-Workflows | Moderat | Höher |
| `gpt-image-1-mini` | High-Volume, Marketing-Visuals, UI-Mockups, kostensensitiv | Schnell | 55–78% günstiger |

Default ist `gpt-image-2`. Auf `gpt-image-1.5` ausweichen wenn Kosten oder Speed dominieren. DALL-E 2 und 3 sind **deprecated** (shutdown 2026-05-12) — nicht verwenden.

**Größen:**

| Wert | Aspect | Einsatz | Kosten |
|---|---|---|---|
| `1024x1024` | Quadrat | Logos, Icons, Social Posts, Avatare | Baseline |
| `1536x1024` | Querformat | Banner, Desktop-Wallpapers, Präsentationen | ~1.5x |
| `1024x1536` | Hochformat | Poster, Personen, Mobile, Stories | ~1.5x |
| `auto` | Modell entscheidet | Bei Unsicherheit | variabel |

Nur `gpt-image-2`: zusätzlich flexible Größen bis 2000 px Breite. Bei Edits gilt: Kantenlänge max. 3840 px, Seiten durch 16 teilbar, Aspect Ratio ≤ 3:1, Gesamt-Pixel zwischen 655.360 und 8.294.400.

**Qualität:**

| Wert | Kosten pro Bild (gpt-image-1.5, 1024x1024) | Einsatz |
|---|---|---|
| `low` | ~$0.009 | Drafts, Prompt-Tests, Previews |
| `medium` | ~$0.034 | Produktiv-Standard |
| `high` | ~$0.133 | Final-Output, Logos, Gesichter, text-lastig |

**Weitere Parameter:**
- `output_format`: `png` (default, Transparenz), `webp` (beste Kompression mit Alpha), `jpeg` (kein Alpha)
- `background`: `opaque` (default), `transparent` (nur mit png/webp, am besten ab quality medium)
- `input_fidelity`: `low` (default) oder `high` (für Gesichter, Logos, Texturen — kostet 2-3x mehr Input-Tokens). **Stand 2026-04-24: bei `gpt-image-2` NICHT unterstützt** — API wirft `400 invalid_input_fidelity_model`. Nur bei `gpt-image-1.5` und `gpt-image-1` einsetzen.
- `moderation`: `auto` (default) oder `low` (weniger restriktiv, nur für verifizierte Konten)
- `n`: Anzahl Varianten (1-10, jede kostet separat)

### Schritt 4: Kosten schätzen

| Modell | Qualität | 1024x1024 | 1536x1024 / 1024x1536 |
|---|---|---|---|
| gpt-image-2 | low–high | OpenAI-Pricing zum Stand 2026-04-24 noch nicht final dokumentiert. Vor produktivem Einsatz auf [platform.openai.com/docs/pricing](https://platform.openai.com/docs/pricing) verifizieren. | s.l. |
| gpt-image-1.5 | low | ~$0.009 | ~$0.013 |
| gpt-image-1.5 | medium | ~$0.034 | ~$0.050 |
| gpt-image-1.5 | high | ~$0.133 | ~$0.200 |
| gpt-image-1 | low | ~$0.011 | ~$0.016 |
| gpt-image-1 | medium | ~$0.042 | ~$0.063 |
| gpt-image-1 | high | ~$0.167 | ~$0.250 |
| gpt-image-1-mini | low | ~$0.005 | ~$0.006 |
| gpt-image-1-mini | medium | ~$0.011 | ~$0.015 |
| gpt-image-1-mini | high | ~$0.036 | ~$0.052 |

Bei Edits mit Eingabe-Bildern: Input-Token-Kosten addieren (Bild-Input: ~323 Tokens pro typischem Bild). Bei `input_fidelity="high"` Input-Bild-Tokens × 2–3. Bei `n > 1` Per-Image-Kosten × n.

Volle Kostentabelle: `references/cost-guide.md`.

### Schritt 5: Generierungs-Plan zeigen

**IMMER** vor der Generierung einen klaren Plan zeigen:

```
## Generierungsplan

**Prompt (optimiert):**
> [optimierter englischer Prompt]

**Einstellungen:**
- Modell: gpt-image-2
- Größe: 1024x1024 (Quadrat)
- Qualität: high
- Format: png
- Hintergrund: transparent
- Anzahl: 1

**Geschätzte Kosten:** ~$X.XX pro Bild (1 Bild = ~$X.XX gesamt)

**Hinweise:** [relevante Notizen, z.B. "High quality wegen Textdarstellung gewählt"]

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

Sprache an Anwender anpassen (Deutsch/Englisch). Plan enthält immer: optimierter Prompt, alle Parameter mit kurzer Begründung bei nicht-offensichtlichen Werten, geschätzte Gesamtkosten, relevante Hinweise.

### Schritt 6: Bestätigung abwarten

**Erst nach expliziter Bestätigung weiter.** Anwender kann:
- Plan bestätigen → generieren
- Prompt ändern → anpassen und erneut zeigen
- Parameter ändern → anpassen und erneut zeigen
- Fragen stellen → beantworten (Advisor Mode), dann zurück zum Plan
- Abbrechen → keine Generierung

### Schritt 7: Generieren

Erst nach Bestätigung via `scripts/generate.py` oder inline-Code generieren.

**Output-Verzeichnis:** Alle Bilder unter `assets/generated_images/` relativ zum Projekt-Root.

**Danach:**
1. Bild dem Anwender per Read-Tool zeigen
2. Tatsächlichen Token-Verbrauch melden (falls API ihn zurückgibt)
3. Temporäre Skripte aufräumen

---

## Wrapper-Funktion und Output-Schema

Die Wrapper-Funktion `generate_image()` in `scripts/generate.py` liefert ein Output-Dict mit vier Pflicht-Schlüsseln:

```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 des verwendeten Prompts
}
```

Dieses Schema ist Bundle-weit verbindlich und wird per Cross-Skill-Eval auf Konsistenz mit anderen Bild-Wrappern geprüft. Optionale Zusatz-Schlüssel sind erlaubt, dürfen die Pflicht-Schlüssel aber nicht überschreiben.

---

## Modell-Limitierungen

### gpt-image-1-mini

Probleme bei: medizinischer Bildinterpretation, kleinem oder gedrehtem Text, nicht-lateinischen Schriften, präzisem räumlichem Reasoning, exaktem Zählen von Objekten. Bei diesen Fällen `gpt-image-1.5` empfehlen.

### Zugriff

Organisations-Verifikation erforderlich vor Zugang zu GPT-Image-Modellen. Physischer Ausweis. Nach Verifikation neuen API-Key erzeugen, um Zugang zu aktivieren.

---

## Endpoint-Auswahl

| Aufgabe | Endpoint | Details |
|---|---|---|
| Text to Image | `client.images.generate()` | Standard, bis zu 10 Varianten via `n` |
| Edit / Multi-Reference-Komposition | `client.images.edit()` | `image` akzeptiert eine Liste von Dateien. OpenAI-Doku zeigt Beispiele mit bis zu 4 Referenzbildern in einem Call. Limit pro Datei <50 MB. |
| Inpainting (maskierter Bereich) | `client.images.edit()` + `mask` | Maske: PNG mit Alpha-Channel, gleiches Format/Größe wie Original, <50 MB. Wirkt auf das erste Eingabebild. |
| Multi-Turn-Editing | Responses API | `previous_response_id` für Kontext |
| Image-Gen im Agent/Chat | Responses API | `tools=[{"type": "image_generation"}]`. Referenzen als URL, Base64-Data-URL oder `file_id` aus Files API. |

---

## Code-Templates

Komplett lauffähige Python-Skripte mit Skill-relativer `.env`-Auflösung.

### Template: Bilderzeugung

```python
import os
import sys
import base64
from pathlib import Path
from datetime import datetime
from openai import OpenAI
from dotenv import load_dotenv

# API Key: zuerst Projekt-.env, dann Skill-assets-.env (Key nie ausgeben)
env_paths = [Path(".env"), Path(__file__).parent.parent / "assets" / ".env"]
for p in env_paths:
    if p.exists():
        load_dotenv(p)
        break

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

output_dir = Path("assets/generated_images")
output_dir.mkdir(parents=True, exist_ok=True)

try:
    result = client.images.generate(
        model="gpt-image-2",  # Default. Alternativen: gpt-image-1.5, gpt-image-1, gpt-image-1-mini
        prompt="YOUR PROMPT HERE",
        size="1024x1024",        # 1024x1024 | 1536x1024 | 1024x1536 | auto
        quality="medium",        # low | medium | high | auto
        output_format="png",     # png | jpeg | webp
        # background="transparent",  # für transparenten Hintergrund (nur png/webp)
        # moderation="low",          # weniger restriktiv (nur verifizierte Konten)
        n=1,
    )

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    for i, item in enumerate(result.data):
        image_bytes = base64.b64decode(item.b64_json)
        suffix = f"_{i+1}" if len(result.data) > 1 else ""
        output_path = output_dir / f"image_{timestamp}{suffix}.png"
        output_path.write_bytes(image_bytes)
        print(f"Image saved: {output_path.resolve()}")

    if hasattr(result, "usage") and result.usage:
        print(f"Tokens — input: {result.usage.input_tokens}, output: {result.usage.output_tokens}")

except Exception as e:
    print(f"Error: {e}")
    sys.exit(1)
```

### Template: Bild-Bearbeitung

```python
import os
import sys
import base64
from pathlib import Path
from datetime import datetime
from openai import OpenAI
from dotenv import load_dotenv

env_paths = [Path(".env"), Path(__file__).parent.parent / "assets" / ".env"]
for p in env_paths:
    if p.exists():
        load_dotenv(p)
        break

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

output_dir = Path("assets/generated_images")
output_dir.mkdir(parents=True, exist_ok=True)

try:
    # Multi-Reference: Liste mit mehreren Bildern möglich (OpenAI-Beispiele bis 4 Referenzen).
    # Typische Anwendungsfälle: Multi-Reference-Portraits (mehrere Winkel) + Outfit-Referenz, Produktbild + Stil-Referenz.
    image_files = [
        open("reference_1.png", "rb"),
        # open("reference_2.png", "rb"),
        # open("reference_3.png", "rb"),
    ]
    # mask_file = open("mask.png", "rb")  # für Inpainting (wirkt auf erstes Bild)

    result = client.images.edit(
        model="gpt-image-2",  # gpt-image-2 beherrscht Multi-Reference-Komposition am besten
        image=image_files if len(image_files) > 1 else image_files[0],
        prompt="YOUR EDIT PROMPT HERE",
        size="1024x1024",
        quality="high",
        # mask=mask_file,              # für Inpainting
        # input_fidelity="high",       # für Gesichter/Logos/Texturen — NICHT mit gpt-image-2 kombinieren
    )

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    image_bytes = base64.b64decode(result.data[0].b64_json)
    output_path = output_dir / f"edited_{timestamp}.png"
    output_path.write_bytes(image_bytes)
    print(f"Edited image saved: {output_path.resolve()}")

finally:
    for f in image_files:
        f.close()
```

Inpainting-Workflow: `references/inpainting.md`. Multi-Turn-Editing via Responses API: `references/responses-api.md`.

---

## Error Handling

Im erzeugten Skript immer einplanen:

```python
import openai

try:
    result = client.images.generate(...)
except openai.AuthenticationError:
    print("API Key ungültig oder nicht gefunden. .env prüfen.")
except openai.RateLimitError:
    print("Rate-Limit erreicht. Kurz warten und erneut versuchen.")
except openai.BadRequestError as e:
    if "content_policy_violation" in str(e):
        print("Content-Policy-Verletzung. Prompt umformulieren.")
    else:
        print(f"Bad request: {e}")
except openai.PermissionDeniedError:
    print("Permission denied. Organisation verifiziert? Check: https://platform.openai.com/settings")
except openai.APIConnectionError:
    print("Netzwerk-Fehler. Internet prüfen.")
except openai.APITimeoutError:
    print("Request-Timeout. Qualität oder Größe reduzieren oder erneut versuchen.")
except Exception as e:
    print(f"Unerwarteter Fehler: {e}")
```

Vollständige Error-Codes: `references/api-params.md`.

---

## Cleanup-Workflow

1. Temporäres Python-Skript ins Projektverzeichnis schreiben
2. Skript ausführen (z.B. `python <script>.py` oder via Anwender-eigenem op-run-Wrapper)
3. Bild in `assets/generated_images/` verifizieren
4. Skript löschen: `rm <script>.py`
5. Bild dem Anwender per Read-Tool zeigen

Niemals temporäre Skripte im Projektverzeichnis liegen lassen.

---

## Feature-Flags und Konfiguration

Die Skill-Config-Beispiel-Datei ist `skill.config.example.yaml`. Wichtige Schlüssel:

- `features.api_key_env_var` — Name der Umgebungsvariable mit dem API-Key. Default: `OPENAI_API_KEY`. Anwender überschreibt nach Bedarf.
- `features.api_timeout_seconds` — Timeout für API-Calls. Default: `60`.
- `features.api_max_retries` — Maximale Retries bei Rate-Limit oder Transient-Errors. Default: `3`.
- `locale` — Sprache für Anwender-Nachrichten. Default: `de`.

Anwender kopiert `skill.config.example.yaml` nach `skill.config.yaml` und passt nur Werte an, die abweichen sollen.

---

## Abhängigkeiten

```
openai>=1.30.0
python-dotenv>=1.0.0
pillow>=10.0.0
```

---

## Referenzdateien

Bei Bedarf laden:

- `references/api-params.md` — Parameter-Referenz, Modell-Vergleich, Rate-Limits, Error-Codes, Pricing
- `references/cost-guide.md` — Kosten-Tabellen, Optimierungs-Strategien
- `references/inpainting.md` — Masken, Alpha-Channels, vollständiger Inpainting-Workflow
- `references/prompt-guide.md` — Prompt-Engineering mit Style-Keywords, Beleuchtung, Komposition
- `references/prompt-patterns.md` — Fertige Prompt-Templates für typische Anwendungsfälle
- `references/responses-api.md` — Multi-Turn-Editing, Streaming, Responses-API
