Emre Demir

Posted on Apr 22 • Originally published at apidog.com

GPT-Image-2 API nutzen: Anleitung und Beispiele

Die gpt-image-2 API ist OpenAIs neuer Endpunkt zur Bilderzeugung, der zusammen mit ChatGPT Images 2.0 am 21. April 2026 veröffentlicht wurde. Wenn Sie bereits die OpenAI Chat- oder Embeddings-APIs verwenden, benötigen Sie für die Integration der neuen Bilderzeugung lediglich eine zusätzliche Anforderungsform, einen API-Schlüssel mit passendem Scope und etwa zehn Minuten Implementationszeit.

Probiere Apidog heute aus

In diesem Leitfaden dreht sich alles um die praktische Nutzung der API: Authentifizierung, Anforderungsparameter, Codebeispiele in drei Sprachen, Denkmodus, Batch-Generierung, Antwortverarbeitung, Fehlercodes, Ratenbegrenzungen und ein Test-Workflow, damit Sie keine Credits durch fehlerhafte Prompts verschwenden. Einen Überblick zu ChatGPT Images 2.0 finden Sie in unserer detaillierten Analyse zu ChatGPT Images 2.0.

Am Ende können Sie produktive API-Aufrufe tätigen, eine wiederverwendbare Apidog-Sammlung für schnelles Prompting nutzen und die Kosten pro Parameter genau einordnen.

Voraussetzungen

Vor dem ersten API-Call benötigen Sie:

Ein OpenAI-Konto mit API-Zugriff (separat von ChatGPT Plus, API-Guthaben ist nicht im ChatGPT-Abo enthalten).
Abrechenbare Nutzungsebene: gpt-image-2 ist ab Stufe 1 verfügbar. Neue Accounts starten im Free-Tier und müssen eine Zahlungsmethode hinterlegen, um Bildendpunkte zu aktivieren.
Einen API-Schlüssel mit images:write-Scope. Für die Produktion sind projektspezifische Keys empfohlen.
Ein Test-Tool, das Bildantworten anzeigen kann. Für erste Tests reicht Curl, danach empfiehlt sich ein API-Client wie Apidog.

Für einfaches Testen den Schlüssel global setzen:

export OPENAI_API_KEY="sk-proj-..."

Endpunkt und Authentifizierung

gpt-image-2 verwendet diesen Endpunkt:

POST https://api.openai.com/v1/images/generations

Authentifizierung erfolgt über Bearer-Token im Authorization-Header. Jede Anfrage enthält einen JSON-Body mit Modell-ID, Prompt und Ausgabeparametern.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Ein scharfes Produkt-Hero-Bild für eine API-Testplattform, dunkler Hintergrund",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Bei Erfolg liefert die API ein JSON mit data-Array (enthält die Bilder). Fehler liefern ein OpenAI-Fehlerobjekt mit code und message. Die wichtigsten Fehler finden Sie weiter unten.

Anforderungsparameter

Jedes Feld im Request beeinflusst Kosten und Ausgabe. Die wichtigsten Parameter:

Parameter	Typ	Werte	Hinweise
`model`	string	`gpt-image-2`	Erforderlich.
`prompt`	string	Bis zu 32.000 Zeichen	Erforderlich. Längere Prompts erhöhen Input-Token-Kosten.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Beeinflusst Ausgabetoken und Kosten.
`quality`	string	`standard`, `high`	`high` kostet ca. doppelt so viel, verarbeitet aber feinen Text/UI besser.
`n`	integer	1–10	Batch-Generierung, geteilter Stil.
`thinking`	string	`off`, `low`, `medium`, `high`	Denkbudget vor dem Rendering.
`response_format`	string	`url`, `b64_json`	URLs laufen nach einer Stunde ab.
`user`	string	Freitext	Für Missbrauchserkennung; idealerweise gehashte User-ID.
`background`	string	`auto`, `transparent`, `opaque`	Transparenz als PNG mit Alpha-Kanal.
`seed`	integer	Beliebige int32	Reduziert Varianz; identische Ausgabe nicht garantiert.

Die Parameter size, quality und thinking bestimmen maßgeblich die Kosten. Beispiel: 2000px, high und thinking: "high" kosten ca. das 4- bis 5-fache von 1024x1024 und standard.

Python-Beispiel

Mit dem offiziellen SDK (openai>=1.50.0) können Sie gpt-image-2 direkt ansprechen:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "Ein minimalistisches Diagramm eines OAuth 2.1 Autorisierungscode-Flows mit PKCE. "
        "Fünf in Englisch beschriftete Kästchen: Benutzer, Client, Auth-Server, Ressourcenserver, Token. "
        "Scharfer serifenloser Text, cremefarbener Hintergrund, türkisfarbene Akzentpfeile."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Generated {len(response.data)} images into {out_dir.resolve()}")

response.data ist immer eine Liste, auch bei n=1. Immer iterieren.
b64_json eignet sich für lokale Skripte; url ist besser für Weiterleitungen an Storage/CDN.

Node.js / TypeScript-Beispiel

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Dashboard UI-Mockup für einen REST-Client, Beschriftungen in Satzschrift, Latenz-Sparkline oben rechts, kühle Graupalette.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Saved ${response.data.length} images`);

Nutzen Sie das offizielle SDK, um Wiederholungen, Idempotenz, Streaming und Schemaänderungen automatisch zu handhaben. fetch ist nur bei Spezialfällen sinnvoll.

Denkmodus: Wann einsetzen?

Der thinking-Parameter steuert, wie viel Planung das Modell vor dem Rendering betreibt:

off: Keine Planung, schnell und günstig. Gut für kreative Prompts ohne feste Komposition.
low: Leichte Planung, Standard für Produktbilder.
medium: Gründliche Planung, optimal für Diagramme, Infografiken, Panels.
high: Maximale Planung, nur für komplexe Layouts oder viele Sprachelemente. Höhere Latenz und Kosten.

Regel: Enthält der Prompt Zahlen, Labels oder Positionsangaben, eine Stufe höher stellen. Für „Stimmungsbilder“ reicht off oder low.

Die OpenAI-Preisseite gibt die Tokenpreise an. Kalkulieren Sie bei medium oder high mit 1,2–2x Grundpreis.

Stapelgenerierung

Mit n > 1 erhalten Sie mehrere stilistisch konsistente Bilder in einer Antwort. Das ist keine parallele Einzelanfrage, sondern ein kohärentes Set – ideal für den Designprozess.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Vier verschiedene Hero-Illustrationen für eine API-Dokumentations-Landingpage, gemeinsame Farbpalette, gemeinsame Linienstärke.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Sie zahlen pro Bild. n=4 kostet etwa das Vierfache von n=1. Der Vorteil ist Konsistenz, nicht Durchsatz.

Antwortformat und Speicherung

b64_json: Bild ist Base64-codiert im Response. Praktisch für Skripte, aber große Dateigrößen (bis 3MB+ bei 2000px PNG).
url: Bild liegt eine Stunde auf dem OpenAI-CDN, Download erforderlich. Optimal für serverlose Pipelines oder bei Größenbeschränkungen.

In Produktion: Bild immer sofort in eigenen Storage (S3, R2, Cloudflare Images) kopieren. Niemals OpenAI-URLs an Endnutzer ausliefern, sie laufen ab.

Fehlerbehandlung & Ratenbegrenzung

gpt-image-2 liefert OpenAI-typische Fehlerstrukturen:

HTTP	`code`	Ursache	Lösung
400	`invalid_request_error`	Ungültige Größe, Verhältnis, Prompt >32k	Größe prüfen, Prompt kürzen.
401	`invalid_api_key`	Key fehlt/falsch	`OPENAI_API_KEY` neu setzen.
403	`insufficient_quota`	Keine Credits/Tier zu niedrig	Abrechnung prüfen, Tier wechseln.
429	`rate_limit_exceeded`	Zu viele Anfragen/min	Mit `Retry-After` verzögern.
429	`image_generation_user_error`	Prompt verletzt Inhaltsrichtlinien	Prompt anpassen.
500	`server_error`	Temporärer OpenAI-Fehler	Mit Backoff erneut versuchen.
503	`overloaded`	Regionale Auslastung	Warten, dann erneut senden.

Rate-Limits sind stufenbasiert (ab ca. 50 Requests/min auf Stufe 1). Prüfen Sie die Header x-ratelimit-remaining-requests und x-ratelimit-remaining-tokens und throtteln Sie pro Antwort.

Wiederholbare Fehlerbehandlung (mit Python):

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

Wichtiger Hinweis: 400er, 401er oder 429er (Policy) nicht erneut versuchen – das verschwendet Credits.

Testen der API mit Apidog

Prompt-Iterationen im Terminal sind langsam und unübersichtlich. Ein spezialisierter API-Client ist deutlich effizienter.

Apidog behandelt gpt-image-2 als erstklassigen Request. Typischer Workflow:

Neue POST-Anfrage in Ihrer OpenAI-Sammlung anlegen, URL https://api.openai.com/v1/images/generations.
Authorization: Bearer {{OPENAI_API_KEY}} als Header, Key per Umgebung setzen.
JSON-Body mit Prompt hinzufügen; Apidog validiert gegen OpenAPI und warnt bei Fehlern.
Absenden – Bilder werden inline angezeigt. Gute Prompts speichern, schlechte markieren, Varianten verzweigen.
Umgebungen für thinking: off, medium, high speichern und Ergebnisse vergleichen.

Das Diffing-Feature von Apidog ist essenziell: Sie vergleichen Parameteränderungen Seite an Seite und bauen eine wiederverwendbare Prompt-Bibliothek für Ihr Team. Terminal-Tools bieten diesen Workflow nicht.

Wer von generischen HTTP-Clients oder instabilen Postman-Workspaces kommt, kann Apidog herunterladen und in unter fünf Minuten mit OpenAI verbinden. Für Teams lohnt sich außerdem der Leitfaden zum API-Testen ohne Postman und die VS Code-Integration von Apidog.

Häufige Fallstricke

quality: "standard" für textlastige Prompts nutzen. Kleine Texte werden verzerrt. Für Labels/UI immer high wählen.
Lange Prompts (>500 Wörter). Über 32.000 Zeichen ist Schluss, aber schon ab einigen hundert Token werden ältere Anweisungen ignoriert. Kürzer ist besser, komplexe Anforderungen durch thinking absichern.
Auf exakte Reproduzierbarkeit durch seed hoffen. Seed reduziert Varianz, garantiert aber keine identische Ausgabe. Für exakte Wiederholung: Bilddaten cachen.
OpenAI-URLs an Endnutzer ausliefern. Sie laufen nach einer Stunde ab. Immer erst in eigenen Storage laden.
Enge Loops gegen den Endpunkt fahren. Bilderzeugung ist langsam. Parallelisieren Sie über Worker, achten Sie auf Ratenbegrenzungen und vermeiden Sie Zeitüberschreitungen durch zu viele sequentielle Anfragen.

FAQ

Wie unterscheidet sich gpt-image-2 von gpt-image-1 auf API-Ebene? Endpunkt und Auth bleiben gleich. Neu: thinking, zusätzliche size-Werte, n bis 10 für Batch. Bestehende SDKs funktionieren nach Modellwechsel weiter, neue Parameter optional. Details in der Analyse zu ChatGPT Images 2.0.

Wie prototypisiere ich eine Integration am schnellsten? Anfrage in Apidog erstellen, zwei Umgebungen (Standard vs. Denkmodus) speichern, Prompts iterieren, ohne Code zu schreiben. Finalen Call als Curl oder SDK-Code exportieren.

Unterstützt die API Bildbearbeitung/Inpainting? Ja, über die bekannten Endpunkte mit neuer Modell-ID. Details in der gpt-image-2-Modellreferenz. Parameter für Masken und Input-Bilder dort dokumentiert.

Darf ich gpt-image-2 kommerziell nutzen? Ja, laut OpenAI-Nutzungsbedingungen. Sie besitzen die generierten Bilder, OpenAI kann Inputs/Outputs zur Missbrauchserkennung verwenden. Prominente/Marken können dennoch Richtlinien triggern.

Was kostet die API im Produktivbetrieb? Ca. $0,21 pro 1024×1024px Bild (high quality, Standardmodus). 10.000 Bilder/Monat ≈ $2.100 (ohne Denkmodus). Für thinking 20–80% Aufschlag einkalkulieren. Vergleiche: GLM 5V Turbo API und Qwen 3.5 Omni als günstigere Alternative bei niedrigerem Qualitätsanspruch.

Gibt es günstigere Alternativen für Textwiedergabe? Noch keine Open-Weight-Modelle mit vergleichbarer Multilingualität. Die Lücke bei Komposition wurde geschlossen, doch CJK- und indische Schriften hinken noch hinterher.