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 aufrufen, dauert das Hinzufügen der Bilderzeugung eine einzige neue Anforderungsform, einen API-Schlüssel mit dem richtigen Berechtigungsumfang und etwa zehn Minuten.

Dieser Leitfaden handelt ausschließlich von der API: Authentifizierung, Anforderungsparameter, Codebeispiele in drei Sprachen, Denkmodus, Stapelgenerierung, Antwortverarbeitung, Fehlercodes, Ratenbegrenzungen und der Test-Workflow, der Sie davor bewahrt, Credits für fehlerhafte Prompts zu verschwenden. Eine Produktübersicht darüber, was neu in ChatGPT Images 2.0 ist, finden Sie in unserer detaillierten Analyse zu ChatGPT Images 2.0.

Am Ende werden Sie funktionierende Aufrufe, eine wiederverwendbare Apidog-Sammlung für die Iteration und ein klares Bild davon haben, was jeder Parameter kostet.

button

Voraussetzungen

Vor Ihrer ersten Anfrage benötigen Sie vier Dinge:

Ein OpenAI-Konto mit API-Zugriff. Entwicklerkonten sind von ChatGPT Plus getrennt; ein ChatGPT-Abonnement beinhaltet keine API-Guthaben.
Eine abrechenbare Nutzungsstufe. gpt-image-2 ist ab Stufe 1 und höher verfügbar. Neue Konten beginnen im Free-Tarif und müssen eine Zahlungsmethode hinzufügen, bevor die Bild-Endpunkte freigeschaltet werden.
Einen API-Schlüssel mit dem images:write-Berechtigungsumfang. Projektspezifische Schlüssel werden gegenüber benutzerspezifischen Schlüsseln für die Produktion empfohlen.
Ein Test-Tool, das Bildantworten vorschaut. Terminal-Curl funktioniert für eine erste Anfrage; danach verwenden Sie einen echten API-Client. Mehr dazu weiter unten.

Setzen Sie den Schlüssel einmal in Ihrer Shell, damit jedes Beispiel in diesem Leitfaden ohne Änderungen ausgeführt wird:

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

Endpunkt und Authentifizierung

gpt-image-2 verwendet denselben Endpunkt zur Bilderzeugung wie das vorherige Modell:

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

Die Authentifizierung erfolgt über ein Bearer-Token im Authorization-Header. Jede Anfrage enthält außerdem einen JSON-Textkörper mit der Modell-ID, dem Prompt und den 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"
  }'

Wenn der Aufruf erfolgreich ist, erhalten Sie ein JSON-Objekt mit einem data-Array von Bildern zurück. Fehler geben ein standardmäßiges OpenAI-Fehlerobjekt mit einem code und einer menschenlesbaren message zurück; die Fehlertabelle weiter unten in diesem Leitfaden behandelt die häufigsten.

Anforderungsparameter

Jedes Feld im Anforderungstext ändert, was Sie bezahlen und was Sie erhalten. Hier ist die vollständige Parameterübersicht für gpt-image-2.

Parameter	Typ	Werte	Hinweise
`model`	string	`gpt-image-2`	Erforderlich.
`prompt`	string	Bis zu 32.000 Zeichen	Erforderlich. Längere Prompts verbrauchen mehr Eingabetoken.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Bestimmt die Anzahl der Ausgabetoken.
`quality`	string	`standard`, `high`	`high` kostet etwa das Doppelte (2x), verarbeitet aber feinen Text und UI-Elemente.
`n`	integer	1–10	Batch-Anfragen teilen den Stil über das gesamte Set.
`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	Wird zur Missbrauchserkennung verwendet; übergeben Sie eine gehashte Benutzer-ID.
`background`	string	`auto`, `transparent`, `opaque`	Transparente Ausgabe wird als PNG mit Alpha-Kanal geliefert.
`seed`	integer	Beliebige int32	Lockere Kontrolle; derselbe Seed plus derselbe Prompt ist ähnlich, aber nicht identisch.

Die drei Parameter, die die Kosten am meisten beeinflussen, sind size, quality und thinking. Ein 2000 Pixel breites Bild in high Qualität mit thinking: "high" kann das 4- bis 5-fache eines Basis-Renderings von 1024x1024 in standard Qualität kosten.

Python-Beispiel

Das offizielle SDK (openai>=1.50.0) bietet native Unterstützung für gpt-image-2:

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()}")

Zwei Dinge, die hervorzuheben sind:

response.data ist eine Liste, auch wenn n=1. Immer iterieren.
b64_json ist einfacher für lokale Skripte; url ist besser, wenn Sie das Bild an ein CDN oder einen S3-Upload weiterleiten, da Sie den Dekodier-dann-Rekodier-Zyklus überspringen.

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`);

Verwenden Sie das offizielle SDK anstelle von rohem fetch, es sei denn, Sie haben einen guten Grund, dies nicht zu tun. Das SDK handhabt Wiederholungsversuche, Idempotenz-Header und Streaming und verfolgt bahnbrechende Schemaänderungen zwischen Modellrevisionen.

Denkmodus: Wann man ihn verwenden sollte

thinking steuert, wie viel Rechenleistung das Modell für die Planung des Layouts vor dem Rendering aufwendet. Vier Werte, ungefähr:

off: keine Überlegung. Am schnellsten, am günstigsten, am besten für lockere kreative Prompts, bei denen die Komposition nicht exakt sein muss.
low: leichte Planung. Ein guter Standard für Produktaufnahmen und Hero-Bilder.
medium: intensivere Planung. Richtige Wahl für Diagramme, Infografiken, Folien und alles mit gezählten Elementen („vier Panels“, „drei Pfeile“).
high: maximale Überlegung. Zahlt sich nur bei komplexen mehrsprachigen Layouts oder strengen technischen Diagrammen aus; erwarten Sie merklich höhere Latenz und Kosten.

Eine praktische Regel: Wenn der Prompt eine Zahl, ein Label oder eine Positionsbeschränkung enthält, gehen Sie eine Stufe höher. Wenn er nur „eine gemütliche Szene“ sagt, gehen Sie eine Stufe tiefer.

Der Denkmodus fügt der Rechnung Überlegungstoken hinzu, zusätzlich zu den Bildausgabetoken. Die OpenAI-Preisseite listet die aktuellen Pro-Token-Preise auf; budgetieren Sie das 1,2- bis 2-fache Ihrer Basis-Bildkosten, wenn medium oder high aktiviert ist.

Stapelgenerierung

Das Setzen von n > 1 gibt mehrere Bilder in einer einzigen Antwort zurück, die Komposition und Stil teilen. Dies ist nicht dasselbe wie das parallele Aufrufen des Endpunkts n-mal; das gibt Ihnen vier nicht zusammenhängende Bilder. Die gebündelte Ausgabe ist kohärent, was der Art und Weise entspricht, wie ein Designteam iteriert.

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, daher kostet n=4 ungefähr das 4-fache von n=1. Der Gewinn ist Konsistenz, nicht Durchsatz.

Antwortformat und Speicherung

Zwei Formate, zwei Anwendungsfälle:

b64_json: Das Bild ist inline in der Antwort enthalten. Einfach für Skripte. Antwort-Payloads werden schnell groß; ein 2000 Pixel breites PNG von hoher Qualität kann die Antwortgröße über 3 MB hinaus treiben.
url: Das Bild liegt eine Stunde lang auf dem CDN von OpenAI, und Sie laden es selbst herunter. Besser für serverlose Funktionen mit Antwortgrößenbeschränkungen und für Pipelines, die das Bild an Ihren eigenen Speicher weiterleiten.

Für die Produktion laden Sie die URL herunter und übertragen Sie diese sofort in Ihren eigenen S3-, R2- oder Cloudflare Images-Bucket. Senden Sie keine OpenAI-URLs an Endbenutzer; sie laufen ab.

Fehlerbehandlung und Ratenbegrenzungen

gpt-image-2 gibt standardmäßige OpenAI-Fehlerstrukturen zurück. Hier sind die, auf die Sie stoßen werden:

HTTP	`code`	Ursache	Lösung
400	`invalid_request_error`	Falsche Größe, nicht unterstütztes Verhältnis, Prompt über 32k Zeichen	Überprüfen Sie die Größenliste und kürzen Sie den Prompt.
401	`invalid_api_key`	Fehlender oder falscher Schlüssel	`OPENAI_API_KEY` neu exportieren.
403	`insufficient_quota`	Keine Credits oder Free-Tier	Abrechnung hinzufügen, Tarif überprüfen.
429	`rate_limit_exceeded`	Zu viele Anfragen pro Minute	Mit Jitter zurückfahren; mit `Retry-After` wiederholen.
429	`image_generation_user_error`	Verweigerung aufgrund der Inhaltsrichtlinien	Prompt umformulieren.
500	`server_error`	Vorübergehendes OpenAI-Problem	Zweimal mit exponentiellem Backoff wiederholen.
503	`overloaded`	Regionale Spitze	Warten und wiederholen.

Ratenbegrenzungen für gpt-image-2 sind stufenbasiert. Auf Stufe 1 beginnen Sie bei etwa 50 Anfragen pro Minute; höhere Stufen skalieren hoch. Lesen Sie immer die Header x-ratelimit-remaining-requests und x-ratelimit-remaining-tokens bei jeder Antwort und drosseln Sie, bevor Sie an die Wand stoßen.

Wiederholbare Fehler in der Produktion:

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")

Versuchen Sie keine 400er, 401er oder 429er (Inhaltsrichtlinien) erneut; diese scheitern aus einem Grund, und erneutes Versuchen verschwendet Credits.

Testen der API mit Apidog

Das Iterieren von Bildgenerierungs-Prompts aus einem Terminal ist langsam: Sie können das Ergebnis nicht sehen, Parameteränderungen nicht vergleichen und die guten Prompts nicht versionieren. Ein speziell entwickelter API-Client löst alle drei Probleme.

Apidog behandelt den gpt-image-2-Endpunkt als eine erstklassige Anfrage. Typischer Workflow:

Erstellen Sie eine neue Anfrage in Ihrer OpenAI-Sammlung, Methode POST, URL https://api.openai.com/v1/images/generations.
Fügen Sie Authorization: Bearer {{OPENAI_API_KEY}} als Header hinzu; setzen Sie OPENAI_API_KEY in einer Umgebungsvariablen, damit es niemals im Quellcode vorhanden ist.
Fügen Sie den JSON-Textkörper mit Ihrem Prompt ein; Apidog validiert gegen die OpenAPI-Spezifikation und zeigt Typenkonflikte an, bevor Sie senden.
Drücken Sie Senden. Bildantworten werden inline gerendert; speichern Sie die guten, markieren Sie die schlechten, verzweigen Sie die Anfrage für Varianten.
Speichern Sie Umgebungen für thinking: off, thinking: medium und thinking: high, um denselben Prompt über verschiedene Denkebenen hinweg zu vergleichen.

Apidogs Anforderungs-Diffing ist hier der wichtigste Teil. Sie optimieren einen Parameter; Sie sehen das Vorher-Nachher-Bild nebeneinander; Sie übernehmen den Gewinner in eine Prompt-Bibliothek, die Ihr gesamtes Team teilt. Dies ist der Workflow, den das Terminal Ihnen nicht bieten kann.

Wenn Sie von einem generischen HTTP-Client oder einem abgestürzten Postman-Workspace kommen, laden Sie Apidog herunter und verknüpfen Sie es mit Ihrem OpenAI-Schlüssel; die Einrichtung dauert weniger als fünf Minuten. Teams, die Alternativen evaluieren, können auch unseren Leitfaden zum API-Testen ohne Postman und die Übersicht über die Apidog VS Code-Erweiterung lesen.

Häufige Fallstricke

Eine Handvoll Fehler verbrennen Credits und Zeit in der ersten Woche mit gpt-image-2.

Verwendung von quality: "standard" für textlastige Prompts. Standardqualität verzerrt kleinen Text. Wechseln Sie zu high, wenn Labels, Icons oder UI-Texte wichtig sind.
Übermäßige Prompt-Nutzung. 32.000 Zeichen sind die Obergrenze, nicht das Ziel. Nach einigen hundert Token beginnt das Modell, frühere Anweisungen zu ignorieren. Halten Sie Prompts unter 500 Wörtern und verwenden Sie thinking, um komplexe Beschränkungen durchzusetzen.
Reproduzierbarkeit von seed erwarten. Seed reduziert die Varianz, fixiert aber die Ausgabe nicht. Wenn Sie genau dasselbe Bild benötigen, cachen Sie die Bytes; generieren Sie es nicht neu.
OpenAI-URLs ausliefern. Sie laufen nach einer Stunde ab. Kopieren Sie immer in Ihren eigenen Speicher, bevor Sie sie nachgelagert bereitstellen.
Den Endpunkt in einer engen Schleife aufrufen. Bilderzeugung ist langsam. Parallelisieren Sie über Worker hinweg und beachten Sie die Ratenbegrenzungs-Header; sequentielle enge Schleifen reihen sich nur ein und verursachen Timeouts.

Häufig gestellte Fragen

Wie unterscheidet sich gpt-image-2 auf API-Ebene von gpt-image-1?Gleicher Endpunkt, gleiche Authentifizierung. Neue Parameter: thinking (off/low/medium/high), zusätzliche size-Werte bis zu 2000 px und n bis zu 10 mit geteiltem Stil. Bestehende SDK-Integrationen funktionieren nach einem Modell-ID-Tausch weiterhin; Sie fügen die neuen Parameter nur dort hinzu, wo sie hilfreich sind. Für den vollständigen Unterschied, siehe die Übersicht zu ChatGPT Images 2.0.

Was ist der schnellste Weg, eine gpt-image-2-Integration zu prototypen?Erstellen Sie eine Anfrage in Apidog, speichern Sie zwei Umgebungen (Standard vs. Denkmodus) und iterieren Sie Prompts, ohne Code zu berühren. Exportieren Sie die finale Anfrage als Curl- oder SDK-Code, wenn Sie bereit sind, sich zu verpflichten.

Unterstützt die API Bildbearbeitung oder Inpainting?Bearbeitungs- und Variationsendpunkte folgen dem gleichen Muster wie die vorherige Generation unter der neuen Modell-ID. Überprüfen Sie die gpt-image-2-Modellreferenz für das neueste Schema; Parameter für Masken und Eingabebilder sind dort dokumentiert.

Kann ich gpt-image-2 für kommerzielle Ausgaben verwenden?Ja, gemäß den Standard-Nutzungsrichtlinien von OpenAI. Sie besitzen die generierten Bilder; OpenAI behält sich das Recht vor, Eingaben und Ausgaben zur Missbrauchsüberwachung zu verwenden. Markenrechtlich geschützte Charaktere und namentlich genannte Persönlichkeiten des öffentlichen Lebens lösen immer noch Schutzmaßnahmen aus.

Wie sieht es mit den Kosten für eine Produktions-Workload aus?Bei etwa 0,21 $ pro 1024×1024 qualitativ hochwertigem Bild im Standardmodus kosten 10.000 Bilder pro Monat etwa 2.100 $ ohne Denkmodus. Fügen Sie 20–80 % für den Denkmodus hinzu. Vergleichen Sie dies mit selbst gehosteten Alternativen wie unserem GLM 5V Turbo API-Leitfaden und der Qwen 3.5 Omni-Integration, wenn das Budget wichtiger ist als die höchste Qualität.

Gibt es eine günstigere Alternative mit ähnlicher Textwiedergabe?Noch nicht in der gleichen Qualität für mehrsprachigen Text. Open-Weight-Modelle haben die Lücke bei der Komposition geschlossen, hinken aber bei CJK- und indischen Schriften immer noch hinterher.

button