So verwenden Sie die gpt-image-2.5 API (Flare und Sunburst) mit curl, Python und Node

OpenAI hat ChatGPT Images 2.5 am 8. September 2026 mit zwei neuen API-Modellen veröffentlicht: gpt-image-2.5-flare und gpt-image-2.5-sunburst. Beide sitzen hinter denselben Endpunkten wie gpt-image-2, sodass die meisten Ihrer Codes ein Modell-ID-Tausch überleben, wenn Sie unserem gpt-image-2 API-Leitfaden gefolgt sind. Was sich geändert hat, ist die Qualitätsskala und wie die Responses API es Ihnen ermöglicht, ein Modell pro Tool-Aufruf auszuwählen.

Dieser Leitfaden behandelt nur den Entwicklerpfad: Generierungen, Mehrteilige Bearbeitungen mit einem Referenzbild und einer Maske, das Responses API-Tool, Streaming und das Auslesen von usage für die realen Kosten. Was die Veröffentlichung für ChatGPT-Benutzer bedeutet, lesen Sie in unserer ChatGPT Images 2.5 Übersicht; der OpenAI Launch Post enthält die Produkteinordnung. Jede Zahl unten stammt aus den OpenAI-Dokumenten, der Preisliste oder dem Rechner, Stand 9. September 2026.

gpt-image-2.5 API auf einen Blick

Die Pro-Token-Preise entsprechen gpt-image-2; die Kosten pro Bild ändern sich jedoch weiterhin, da sich die Token-Anzahl pro Qualitätsstufe geändert hat.

Voraussetzungen

• Ein OpenAI-Entwicklerkonto mit einem kostenpflichtigen Nutzungstarif. Bild-Endpunkte benötigen Tier 1 oder höher, was das Hinzufügen einer Zahlungsmethode bedeutet; ein ChatGPT-Abonnement zählt nicht. Unser OpenAI API-Schlüssel-Walkthrough behandelt projektbezogene Schlüssel.
• Das offizielle openai SDK für Python oder Node.
• Eine Möglichkeit, Bildantworten in der Vorschau anzuzeigen. curl gibt Base64 aus, was für die Iteration mühsam ist; Apidog rendert das dekodierte Bild direkt, und der letzte Abschnitt beschreibt den Workflow dort.

Schlüssel einmal exportieren:

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

Ein Bild mit curl generieren

Verwenden Sie zuerst Flare; OpenAIs Modellseite bezeichnet es als „die Standardwahl für die meisten Anwendungen“.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

Die Antwort enthält ein data-Array mit einem b64_json pro Bild, plus ein usage-Objekt mit input_tokens und output_tokens. Behalten Sie usage bei; es ist das einzige genaue Kostensignal, das Sie erhalten. Parametrierungshinweise aus dem Bilderzeugungsleitfaden: output_format ist standardmäßig png und OpenAI sagt „Die Verwendung von jpeg ist schneller als png“; output_compression (0-100) gilt nur für jpeg und webp; background: "transparent" schlägt bei jpeg fehl.

Python: Generieren, dann mit einem Referenzbild bearbeiten

Der SDK-Aufruf spiegelt den curl-Body wider. Dekodieren Sie b64_json und schreiben Sie die Bytes.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

Bearbeitungen sind der Punkt, an dem die 2.5-Modelle ihren Wert beweisen; der Launch-Post besagt, dass sie „besser darin sind, nur das zu bearbeiten, worum Sie gebeten haben, während der Rest der Details gleich bleibt“, und OpenAI positioniert Sunburst für „präzisere Kontrolle bei Bearbeitungen“. Der Bearbeitungs-Endpunkt ist mehrteilig: ein Referenzbild, eine optionale Maske und ein Prompt. Wo die Maske transparent ist, malt das Modell neu; überall sonst behält es das Original bei.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

Lassen Sie mask weg, und das Modell entscheidet, was nur aus dem Prompt geändert werden soll. Das Referenzbild wird als Bild-Eingabe-Token zu 8 $ pro 1 Mio. abgerechnet; OpenAI veröffentlicht keine Pro-Bild-Eingabe-Token-Anzahl, daher lesen Sie usage.input_tokens.

Node und TypeScript: b64_json auf Festplatte schreiben

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

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

Verwenden Sie `gpt-image-2.5-flare-2026-09-08` in der Produktion, um die Ausgabe stabil zu halten, während der Alias sich bewegt.

Responses API: Bilderzeugung als Tool

Hier liest ein Hauptmodell Ihren Prompt, überarbeitet ihn und ruft das image_generation Tool auf. Sie wählen das Bildmodell, indem Sie model innerhalb der Tool-Definition festlegen; das Top-Level-model muss ein Hauptmodell sein, und OpenAIs Tool-Dokumentation verwendet gpt-6-astra. Unser Responses API-Leitfaden behandelt das Anfrageformat. Das action-Feld nimmt auto (Standard), generate oder edit an; setzen Sie edit, wenn Sie ein Referenzbild übergeben und es modifiziert, nicht neu interpretiert haben möchten.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

Die `previous_response_id`-Folgeanfrage hält das erste Bild im Kontext, sodass „gleiche Szene“ ohne erneutes Hochladen der Datei aufgelöst wird. Hauptmodell-Token werden zusätzlich zu den Bild-Token abgerechnet, und die Prompt-Umschreibung bedeutet, dass Sie die Ausgabe nicht allein aus dem Prompt-Text reproduzieren können.

Streaming von Teilbildern

Beide APIs akzeptieren partial_images (0 bis 3). Jedes Teilbild kostet 100 zusätzliche Ausgabe-Token, sodass drei 300 Token oder 0,009 $ pro Bild hinzufügen. Das lohnt sich für eine Benutzeroberfläche, die den Fortschritt anzeigt; in einem Batch-Job wäre es verschwendet.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

Die genauen Event-Typ-Strings finden Sie im Bilderzeugungsleitfaden; die Suffix-Prüfung sorgt dafür, dass die Schleife über beide API-Varianten hinweg funktioniert. Um gestreamte Events außerhalb des Codes zu untersuchen, lesen Sie unseren Leitfaden zum Testen von SSE-Antworten von KI-APIs.

Nutzung lesen und Token in Dollar umwandeln

OpenAIs eigener Vorbehalt: „Gleiche Token-Raten bedeuten nicht gleiche Kosten pro Bild: der Token-Verbrauch kann je nach Modell und Qualitätseinstellung variieren.“ Der Rechner im Bilderzeugungsleitfaden gibt diese Schätzungen für Bild-Ausgabe-Token allein an, zu einem Preis von 30 $ pro 1 Mio. auf der Preisliste:

Beachten Sie die Umbenennung. `high` bei 2.5 verwendet 1.756 Token, das alte `medium`-Budget bei `gpt-image-2`; `max` verwendet 7.024 Token, das alte `high`-Budget. Behalten Sie `quality: "high"` bei einer Migration bei, und jedes Bild wird etwa 4x günstiger zum alten `medium`-Budget; für das alte `high`-Budget wechseln Sie zu `max`. Unser Flare vs Sunburst vs gpt-image-2 Vergleich berechnet die vollständigen monatlichen Kosten.

Rechnerwerte sind Schätzungen. Die tatsächlichen Kosten ergeben sich aus der Antwort:

OUTPUT_RATE = 30 / 1_000_000  # Dollar pro Bild-Ausgabe-Token
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

Pro Anfrage protokollieren; laut OpenAI kann eine größere, nicht-quadratische Größe weniger Token produzieren als eine kleinere, quadratische. Eine offene Frage: Die Batch-Registerkarte der Preisliste führt nur `gpt-image-2` auf, daher ist die Unterstützung der Batch API für 2.5 als unbestätigt zu behandeln.

Fehler, Ratenbegrenzungen und Timeouts

• 429 Ratenbegrenzung. Mit Jitter zurückziehen und `Retry-After` respektieren. Die 2.5-Modellseiten veröffentlichen keine tierbezogenen Limits. Als Referenz läuft `gpt-image-2` in Tier 1 mit 5 Bildern pro Minute und 100k TPM, skalierend auf Tier 5 mit 250 IPM und 8M TPM.
• insufficient_quota. Keine Credits oder immer noch im kostenlosen Tarif. Abrechnung hinzufügen; nicht erneut versuchen.
• Moderationsablehnungen. Der Prompt oder das Referenzbild hat den Filter ausgelöst. Neu formulieren statt erneut versuchen; `moderation: "low"` lockert die Schwelle.
• Timeouts. OpenAI dokumentiert, dass "komplexe Prompts bis zu 2 Minuten zur Verarbeitung benötigen können". Client-Timeouts entsprechend höher setzen; Sunburst läuft designbedingt länger als Flare.

Flare und Sunburst nebeneinander in Apidog testen

Die Iteration von Bild-Prompts im Terminal ist langsam, da Sie die Ausgabe nicht sehen können, und ein falscher `quality`-Wert kostet bei jeder Sendung echtes Geld. Apidog ist ein API-Client und eine Testplattform: Es sendet die Aufrufe und prüft die Antworten; OpenAIs Server übernehmen das Rendering.

1. Den Schlüssel einmal speichern. Fügen Sie `OPENAI_API_KEY` als Umgebungsvariable hinzu und referenzieren Sie es als `Bearer {{OPENAI_API_KEY}}` im Authorization-Header; der Schlüssel gelangt niemals in eine gespeicherte Anfrage.
2. Zwei Umgebungen, eine Anfrage. Erstellen Sie Umgebungen namens `flare` und `sunburst`, jede mit einer `MODEL`-Variablen, und setzen Sie `"model": "{{MODEL}}"` im Body. Wechseln, erneut senden und Bilder sowie `usage` nebeneinander vergleichen. Für Bearbeitungen verwenden Sie einen Form-Data-Body mit `image` und `mask` als Dateifeldern.
3. b64_json in einem Post-Prozessor dekodieren. Ein kurzes Skript extrahiert `data[0].b64_json`, dekodiert es und speichert die Datei, sodass jede Sendung ein anzeigbares Bild neben dem rohen JSON liefert.
4. Kosten überprüfen, dann planen. Prüfen Sie, dass `usage.output_tokens` ein Budget einhält, z.B. 2.000 für ein hohes 1536x1024-Rendering, und führen Sie die Anfrage als zeitgesteuerten Regressionstest aus. Wenn jemand die Qualität auf `max` erhöht oder ein Snapshot die Token-Anzahl verschiebt, schlägt der Test fehl, bevor die Rechnung kommt.

Laden Sie Apidog herunter, verbinden Sie es mit Ihrem OpenAI-Schlüssel, und Sie haben eine gemeinsame Prompt-Bibliothek mit Kosten-Schutzmaßnahmen.

Häufig gestellte Fragen (FAQ)

Muss ich meinen gpt-image-2-Code ändern, um 2.5 zu verwenden? Tauschen Sie die Modell-ID aus und überprüfen Sie die `quality` erneut. Endpunkte, Authentifizierung und Antwortformat bleiben unverändert, aber `high` ist jetzt einem kleineren Token-Budget zugeordnet. Der gpt-image-2 API-Leitfaden behandelt weiterhin das ältere Modell.

Flare oder Sunburst für die API? Beginnen Sie mit Flare. OpenAI positioniert es als Standard mit „50 % geringerer Latenz“ als `gpt-image-2` zum gleichen Preis pro Token. Wechseln Sie zu Sunburst, wenn die Bearbeitungsgenauigkeit wichtiger ist als die Geschwindigkeit, z. B. bei Produktbildern, die aus Referenzfotos erstellt wurden. Beide teilen sich die gleichen Token-Anzahlen im Rechner, der Kompromiss liegt also bei der Zeit, nicht bei den Dollars.

Kann ich diese Modelle in Chat Completions verwenden? Nein. Die Bilderzeugung erfolgt über die Image API und das Responses API `image_generation` Tool. Chat Completions macht dies nicht verfügbar.

Gibt es eine kostenlose Möglichkeit, 2.5 über die API auszuprobieren? Es gibt keinen dauerhaften kostenlosen API-Tier, und Bild-Endpunkte benötigen Tier 1. Der günstigste reale Weg ist `quality: "low"` mit 196 Tokens, etwa 0,006 $ pro 1024x1024 Bild. Die Consumer-App ist eine andere Sache; siehe wie man ChatGPT Images 2.5 kostenlos nutzt.

Nächste Schritte

Beginnen Sie mit dem curl-Aufruf, bestätigen Sie `usage.output_tokens` anhand der Rechnertabelle, und verschieben Sie dann die Anfrage in einen Client, wo Sie das Bild sehen können. Simon Willisons Beitrag zeigt, wie Sunburst eine Grafik intakt hält, während ein Motiv hinzugefügt wird; testen Sie dieses Bearbeitungsverhalten an Ihren eigenen Referenzbildern, bevor Sie sich festlegen.