So verwendest du die GPT-Image-2.6 API

Die GPT-Image-2.6-API generiert und bearbeitet Bilder über zwei OpenAI-Modelle: gpt-image-2.6-flare und gpt-image-2.6-sunburst. Sende einen Prompt an POST /v1/images/generations mit deinem API-Schlüssel und dekodiere anschließend b64_json aus der Antwort. Version 2.6 ergänzt Bild-Markup, SVG- und GIF-Ausgabe sowie einen complexity-Parameter.

Dieser Leitfaden behandelt Authentifizierung, eine erste Generierung, eine Markup-Bearbeitung, SVG-Export sowie die Einstellungen für quality und complexity. Er konzentriert sich auf das Neue – lies daher unseren GPT-Image-2.5-API-Leitfaden für Streaming und das Responses-API-Tool und unseren ChatGPT-Images-2.6-Erklärartikel für das vollständige Release. Alle untenstehenden Anfragen haben wir am 5. November 2026 auf Basis der OpenAI-Dokumentation erstellt. Wir haben sie nicht mit einem Live-Schlüssel getestet – probiere sie also aus, bevor du sie produktiv einsetzt.

GPT-Image-2.6-API auf einen Blick

Die Preise stammen von der OpenAI-Preisseite. Beide Modelle kosten pro Token gleich viel – entscheide dich also nach Geschwindigkeit und Bearbeitungspräzision.

Flare oder Sunburst: Welches Modell solltest du aufrufen?

Rufe Flare für schnelle Iteration und alltägliche Generierung auf. Laut OpenAI kann es bei low-Qualität ein Bild in nur sechs Sekunden zurückgeben und verbessert das Layout für Poster und Produktbilder. Rufe Sunburst für detaillierte Arbeiten und wiederholte Bearbeitungen auf, bei denen OpenAI eine bessere Konsistenz bei medium- oder high-Qualität verspricht.

Das sind OpenAIs Angaben, keine unabhängigen Benchmarks. Unser Flare-vs.-Sunburst-Vergleich für 2.5 erklärt die Aufteilung.

Authentifizierung und Einrichtung

Du brauchst drei Dinge vor deinem ersten Aufruf:

1. Erstelle einen API-Schlüssel im OpenAI-Dashboard und exportiere ihn als OPENAI_API_KEY.
2. Schließe die API-Organisationsverifizierung ab, falls deine Organisation sie benötigt. Laut OpenAI kann sie erforderlich sein, bevor du GPT-Image-Modelle verwenden kannst.
3. Installiere jq für die curl-Beispiele oder das openai-Paket für Python.

Wenn deine App einzelne Nutzer bedient, sende außerdem eine gehashte safety_identifier mit bis zu 128 Zeichen. Sie ersetzt den veralteten user-Parameter.

Generiere dein erstes Bild

Diese Anfrage verwendet Flare mit low-Qualität, was sich für Entwürfe eignet.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
    "size": "1024x1536",
    "quality": "low",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > poster.png

Derselbe Aufruf in Python:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.6-sunburst",
    prompt="A product shot of a ceramic mug on a walnut desk, soft morning light",
    size="1536x1024",
    quality="medium",
    extra_body={"complexity": "low"},
)

Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))

Wir übergeben complexity über extra_body, damit der Aufruf nicht davon abhängt, ob deine SDK-Version es als benanntes Argument bereitstellt. GPT-Image-Modelle geben immer base64 zurück – sende also kein response_format und suche nicht nach einem url-Feld.

OpenAIs Leitfaden empfiehlt, das usage-Objekt der Antwort zu lesen, um die Token-Nutzung zu messen. Die API-Referenz beschreibt dieses Feld jedoch als nur für gpt-image-1 gültig, obwohl ihre Beispielantwort es enthält – vergewissere dich also, dass es in deinen 2.6-Antworten erscheint, bevor du darauf dein Kosten-Tracking aufbaust.

Bearbeite ein Bild mit Markup

Markup sagt dem Modell, wo eine Änderung vorgenommen werden soll. Du sendest das Originalbild, ein transparentes PNG mit deinen Kreisen oder Skizzen und einen Prompt, der die Bearbeitung beschreibt.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
    "markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
    "prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
    "quality": "medium",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > vase.png

JSON-Anfragen verwenden das images-Array und ein markup-Objekt, das genau eines von image_url oder file_id enthält. Eine image_url kann eine HTTPS-URL oder eine base64-Daten-URL sein. Multipart-Anfragen nehmen stattdessen einen Datei-Upload entgegen – die entsprechende Version in Python findest du im Leitfaden zur Bildgenerierung.

Für das Overlay gelten strenge Regeln:

• Nach der Ausrichtung muss es in Breite und Höhe dem ersten Bild entsprechen.
• Es muss transparente Pixel enthalten – flache es also nicht auf das Foto ab.
• Es wird auf das erste Eingabebild angewendet. Alle weiteren dienen als Referenzen.
• Jedes der beiden Bilder darf höchstens 16.777.216 Pixel enthalten, und die Overlay-Datei darf 50 MB nicht überschreiten.
• Du kannst markup nicht mit mask oder prompt_rewriter kombinieren.

Weise das Modell an, die Anmerkung zu entfernen, so wie es auch OpenAIs eigenes Beispiel macht. Markup kostet dasselbe wie jede andere Bearbeitung. Die Responses-API unterstützt es nicht – verwende dort stattdessen eine Maske.

SVG exportieren

Setze output_format auf svg beim Generations-Endpunkt für Icons, Logos und Illustrationen, die bearbeitbare Pfade benötigen.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
    "output_format": "svg",
    "quality": "medium",
    "n": 1
  }' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg

Die API rendert zunächst ein Referenzbild, das quality steuert, und schreibt daraus das SVG. Die dekodierten Bytes sind UTF-8-XML ohne Skripte, externe Ressourcen oder eingebettete Rastergrafiken.

Es gelten vier Einschränkungen:

• n muss 1 sein.
• Streaming, partielle Bilder, output_compression und prompt_rewriter funktionieren nicht.
• Der Edits-Endpunkt kann kein SVG ausgeben und akzeptiert kein SVG als Rastereingabe.
• Das optionale svg-Objekt wählt das Autorenmodell aus, aber nur, wenn dein Konto über SVG-Modellauswahl verfügt. Andernfalls lasse es weg.

Du zahlst doppelt: den Bildpreis für das Referenzbild und den Preis des Autorenmodells für dessen Tokens. Die API-Referenz führt für diesen zweiten Teil ein separates svg_usage-Objekt auf – protokolliere es also.

Ein GIF generieren

Die API gibt ein fertiges GIF zurück, kein Sprite-Sheet. Füge einer Generations-Anfrage drei Felder hinzu:

{
  "model": "gpt-image-2.6-flare",
  "prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto"
}

Dekodiere b64_json auf dieselbe Weise und speichere es als .gif. Prüfe zuvor zwei Dinge:

• Frame-Limit. Der Leitfaden besagt, dass frame_count von 2 bis 64 reicht. Die API-Referenz gibt 2 bis 16 an. Bleibe bei 16 oder darunter, bis du höhere Werte getestet hast.
• Zugriff. Die Referenz besagt, dass die GIF-Ausgabe Zugriff auf die GIF-Vorschau für das ausgewählte Modell erfordert, während der Leitfaden dies nicht erwähnt. Eine abgelehnte GIF-Anfrage kann ein Zugriffsproblem sein, kein fehlerhaftes Payload.

Die GIF-Ausgabe unterstützt kein Streaming, keine partiellen Bilder und keine benutzerdefinierte output_compression, und der Edits-Endpunkt kann sie nicht zurückgeben. OpenAI veröffentlicht keine GIF-spezifische Abrechnungsformel – führe also einen kleinen Test durch und prüfe deine Rechnung, bevor du skalierst.

Quality und Complexity festlegen

quality steuert den Rendering-Detailgrad und treibt die Token-Kosten. complexity steuert, wie viel das Modell vor dem Rendern plant – eine Änderung daran verursacht keine separaten Kosten.

Setze complexity bei jeder Anfrage. Der Standard ist high, doch OpenAI empfiehlt low für die meisten Bearbeitungen. Der Leitfaden warnt, dass höhere Einstellungen die Latenz erhöhen und unerwünschte Änderungen einführen können.

Quality bestimmt außerdem deine Ausgaberechnung. Diese Tabelle verwendet OpenAIs Rechner für ein 1024x1024-Bild, abgelesen am 5. November, und schließt Input-Tokens aus:

Der Unterschied zwischen medium und high beträgt etwa einen Cent – vergleiche also beide. Der Batch-Tab der Preisseite listet 2.6 noch nicht auf – gehe also nicht davon aus, dass der Batch-Rabatt von 2.5 gilt.

Fehler und Timeouts behandeln

Sortiere Fehler danach, ob ein erneuter Versuch helfen kann:

Verwende error.code als deine stabile Prüfung und protokolliere die Request-ID. moderation_details enthält moderation_stage und grobe categories, die in deine Logs gehören, nicht in benutzerseitige Meldungen. Setze Client-Timeouts auf über zwei Minuten, denn laut OpenAI können komplexe Prompts so lange dauern.

Lass deinen Coding-Agent es mit Apidog CLI testen

Dein Coding-Agent kann diese Anfragen und Limits mit Apidog CLI in eine Testsuite verwandeln. Richte es einmal ein:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Gib dann Claude Code, Codex oder Cursor einen Prompt:

In Apidog project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the bearer token from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.

Der Agent liest jedes Schema, validiert sein Payload und schreibt und führt dann die Suite aus:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog cli-schema validate test-suite-create --file suite.json
apidog test-suite create --project <id> --file suite.json
apidog test-suite run <suiteId> --project <id> -e <envId> \
  --env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json

Fall 5 klärt das Frame-Limit für dein Konto, und Fall 3 zeigt, ob du GIF-Zugriff hast. Erfolgreiche Fälle erzeugen echte, kostenpflichtige Generierungen – halte quality also niedrig. Ersetze durch -r junit, um die Suite in einer CI-Pipeline auszuführen, und sieh dir den Claude-Code-Einrichtungsleitfaden für Agent-Details an.

FAQ

Wie lauten die Modellnamen der GPT-Image-2.6-API? gpt-image-2.6-flare und gpt-image-2.6-sunburst. Die API-Referenz listet für sie noch keine datierten Snapshots auf, anders als bei den 2.5-Modellen.

Wie viel kostet die GPT-Image-2.6-API? Bild-Tokens kosten $8 pro 1 Mio. Input und $30 pro 1 Mio. Output. Ein 1024x1024-Bild kostet etwa $0,025 im Output bei low und etwa $0,053 bei high, noch vor Input-Tokens.

Sollte ich von gpt-image-2.5 migrieren? Migriere, wenn du SVG, GIF oder complexity benötigst. Teste zuerst deine Kosten: Ein low-Bild verbraucht etwa 4,2-mal so viele Tokens wie bei 2.5, und für die 2.6-Modelle ist noch keine Batch-Preisgestaltung aufgeführt.

Kann ich complexity beim Edits-Endpunkt verwenden? Ja. OpenAI empfiehlt low für die meisten Bearbeitungen.

Kann ich ein hochgeladenes Bild über die API in ein GIF umwandeln? Nein. Der Edits-Endpunkt gibt weder GIF noch SVG zurück – beide Formate starten also von einem Text-Prompt beim Generations-Endpunkt.

Gibt die API eine URL zurück? Nein. GPT-Image-Modelle geben immer base64 in b64_json zurück – dekodiere es also und speichere die Datei selbst.