GPT Image 2 / 2.5: Generierung und Bildbearbeitung

Wählen Sie den Endpunkt, bevor Sie die Anfrage schreiben: Text-zu-Bild verwendet /images/generations; Bild-zu-Bild verwendet /images/edits mit hochgeladenen Bilddateien. Die Erwähnung von „Referenzbild 1“ in einem Prompt hängt kein Bild an.

Modelle und Endpunkte

Modell-ID	Text-zu-Bild	Bild-zu-Bild
gpt-image-2	/images/generations	/images/edits + Bilddateien
gpt-image-2.5-sunburst	/images/generations	/images/edits + Bilddateien
gpt-image-2.5-flare	/images/generations	/images/edits + Bilddateien

Dies sind unterschiedliche Modell-IDs. Ändern Sie model beim Modellwechsel explizit; GPT Image 2.5 ist kein Alias von GPT Image 2. Aktuelle Verfügbarkeit und Kontopreise prüfen Sie im Marktplatz.

Operation	Methode und Endpunkt	Anfrageformat
Text-zu-Bild	POST https://apimaster.ai/v1/images/generations	JSON
Bild-zu-Bild / Bearbeitung	POST https://apimaster.ai/v1/images/edits	multipart/form-data mit tatsächlichen Bilddateien
Asynchrone Bildbearbeitung	POST https://apimaster.ai/v1/images/edits/async	Gleiche Multipart-Dateien wie bei Edits; liefert eine Task-ID zurück
Asynchrones Text-zu-Bild	POST https://apimaster.ai/v1/images/generations/async	JSON; liefert eine Task-ID zurück
Task abfragen	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Bearer-Authentifizierung

Für eine Task-Antwort aus der Bildbearbeitung verwenden Sie /images/edits/async. Laden Sie dieselben Dateien und Felder hoch wie bei synchronen Edits und fragen Sie anschließend /tasks/{task_id} ab. Verlagern Sie eine Bearbeitungsanfrage nicht auf generations/async. Diese Task-Endpunkte nutzen denselben bestehenden asynchronen Vertrag: Ein asynchroner Upstream kann seine Task umgehend zurückliefern, während ein synchroner Upstream die Bearbeitung abschließen kann, bevor das Gateway eine Task-ID zurückgibt. Sie sind kein Versprechen sofortiger Hintergrundausführung. Verwenden Sie Chat Completions nicht für diese Modelle.

Authentifizierung und Timeouts

API-Schlüssel erstellen und senden Sie Authorization: Bearer YOUR_API_KEY. JSON-Generierungsanfragen verwenden Content-Type: application/json. Bei Datei-Uploads überlassen Sie es cURL oder Ihrer HTTP-Bibliothek, die Multipart-Boundary zu generieren; setzen Sie den Content-Type-Header nicht manuell.

Planen Sie mindestens 180 Sekunden für einfache Anfragen, 300 Sekunden für höhere Auflösung und 600 Sekunden für anspruchsvolle Edits oder hohe Qualität ein. Ein Client-Timeout beweist nicht, dass die Upstream-Anfrage gestoppt wurde. Vermeiden Sie unmittelbare doppelte Übermittlungen.

Text-zu-Bild: JSON-Generierung

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Ersetzen Sie für Sunburst oder Flare die Modell-ID durch gpt-image-2.5-sunburst oder gpt-image-2.5-flare. Fügen Sie diesem Beispiel keine Referenzbilder hinzu; verwenden Sie die Bearbeitungsbeispiele unten.

Bild-zu-Bild: eine Referenz hochladen

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Ersetzen Sie reference.png durch ein vorhandenes lokales Bild. Das @ weist cURL an, Dateibytes hochzuladen; image=reference.png sendet nur eine Dateinamen-Zeichenkette. Dieses Endpunktmuster gilt auch für gpt-image-2 und gpt-image-2.5-sunburst.

Bild-zu-Bild: mehrere Referenzen hochladen

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Wiederholen Sie dasselbe Feld image[] für jede Datei, in der vom Prompt beschriebenen Reihenfolge. n ist die Anzahl der Ausgabebilder, nicht die Anzahl der Referenzen. Referenzlimits hängen vom ausgewählten Modell und der verfügbaren Route ab; nehmen Sie nicht ein universelles Limit von 16 Bildern an. Beginnen Sie mit einer Referenz und n=1 und fügen Sie dann bei Bedarf weitere Eingaben hinzu.

Bearbeitungsbeispiel in Python

Installieren Sie requests. Dieses Beispiel lädt eine echte Datei hoch und verarbeitet sowohl URL- als auch Base64-Bildantworten.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Übergeben Sie bei mehreren Dateien eine Liste wiederholter ("image[]", (filename, file_object, mime_type))-Einträge an files. Halten Sie jede Datei geöffnet, bis die Anfrage abgeschlossen ist.

Asynchrone Bildbearbeitung

Verwenden Sie diesen Endpunkt mit GPT Image 2, Sunburst oder Flare, wenn Ihre Anwendung Task-IDs verarbeitet. Datei-Upload-Regeln, Referenzreihenfolge, Fähigkeitsgrenzen und Authentifizierung sind dieselben wie bei synchronen Edits.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Die Übermittlung gibt data[0].task_id zurück. Fragen Sie mit derselben Modell-ID ab:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ein abgeschlossener getrackter Task hat diese Form; jedes generierte Bild ist enthalten:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

Der Task gehört zum Konto, das ihn übermittelt hat. Fragen Sie ihn mit einem gültigen API-Schlüssel für dieses Konto ab. Eine fehlgeschlagene Übermittlung gibt einen Fehler statt eines brauchbaren Tasks zurück; sobald eine Task-ID zurückgegeben wurde, fragen Sie diesen Task weiter ab, statt die Bearbeitung erneut zu übermitteln. Siehe die Tabelle zu den Polling-Statuswerten unten.

Vorhandene URL- oder Base64-Integrationen

Wenn Ihre Eingabe eine URL ist, laden Sie das Bild in Ihrer Anwendung herunter und laden Sie dessen Bytes zu /images/edits hoch. Wenn es eine Base64-Data-URI ist, dekodieren Sie die Nutzdaten in eine Datei oder einen Byte-Puffer und laden Sie diese hoch. Übermitteln Sie die URL oder den Base64-Text nicht so, als wäre es ein Datei-Upload.

Einige GPT Image 2-Routen unterstützen die Erweiterung image_urls auf generations. Das ist kein portabler Vertrag für die Bildbearbeitung und darf nicht als funktionierend mit GPT Image 2.5 angenommen werden. Neue Integrationen sollten die Multipart-Edits-Beispiele oben verwenden. Eine JSON-Anfrage, die image_urls, image oder images enthält, ist nicht gleichbedeutend mit dem Hochladen von Dateien zu Edits.

Parameter und Fähigkeitsgrenzen

Feld	Verwendung
model	Erforderlich; verwenden Sie eine exakte Modell-ID aus der Tabelle oben
prompt	Erforderlich; beschreiben Sie das Ergebnis und die Referenzreihenfolge
image / image[]	Tatsächlich hochgeladene Dateien für Edits; verwenden Sie PNG oder JPEG für die Basisbeispiele
n	Anzahl der Ausgabebilder; beginnen Sie mit 1; das Maximum hängt von der Route ab
size	Optional; 1024x1024 ist das Basisbeispiel; andere Pixelabmessungen oder Seitenverhältnisse hängen von der Route ab
resolution	Optionale routenspezifische Erweiterung wie 1k, 2k, 4k; nicht jedes Modell/jede Route unterstützt jede Stufe
quality	Optional; akzeptierte Werte und Kosten hängen von der Route ab
background, output_format, output_compression	Optional; Transparenz und Ausgabekodierung erfordern Routenunterstützung
mask	Nur GPT Image 2, wenn eine verfügbare Edits-Route hochgeladene Masken unterstützt; wird vom aktuellen GPT Image 2.5-Multipart-Handler nicht unterstützt

Bei GPT Image 2 muss die Maskenunterstützung separat von der gewöhnlichen Referenzbearbeitung geprüft werden. Eine kompatible PNG-Maske muss den Eingabeabmessungen entsprechen und einen Alphakanal enthalten. Der aktuelle GPT Image 2.5-Multipart-Endpunkt weist hochgeladene Maskendateien zurück; fügen Sie den Sunburst- oder Flare-Beispielen oben keine Maske hinzu. Nehmen Sie nicht an, dass ein JSON-Workaround mit mask_url unterstützt wird, ohne die gewählte Route zu prüfen.

Senden Sie nur die optionalen Felder, die Sie benötigen. Sie können die infrage kommenden Routen und den Preis ändern; das ausdrückliche Setzen eines Standardwerts ist nicht immer gleichbedeutend mit dem Weglassen. Keine feste Tabelle mit Pixelgrößen oder Liste erweiterter Parameter gilt einheitlich für alle drei Modell-IDs. Tatsächliche Preise und unterstützte Fähigkeiten richten sich nach dem Marktplatz und der Anfrageantwort.

Synchrone Antworten

Eine erfolgreiche Generierung oder Bearbeitung liefert Bildeinträge in data zurück:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Je nach Route und Ausgabeformat kann ein Eintrag stattdessen b64_json enthalten. Dekodieren Sie es zu Bildbytes. Laden Sie temporäre Ergebnis-URLs umgehend herunter. Eine HTTP-200-Antwort oder eine Bildanzahl allein beweist nicht, dass Referenzdetails erhalten geblieben sind; prüfen Sie das Ergebnis gegen die Eingabe.

Asynchrone Tasks: Übermittlung und Polling

Übermitteln Sie für Text-zu-Bild JSON ohne Referenzbilder an generations/async. Verwenden Sie für Bildbearbeitung das Multipart-edits/async-Beispiel oben. Beide verwenden denselben Task-Abfrage-Endpunkt:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

Der Envelope der Übermittlungsantwort meldet normalerweise submitted; ein Upstream meldet möglicherweise bereits einen Abschlusszustand. Die erste Abfrage kann bereits abgeschlossen sein. Eine Task-ID garantiert keine sofortige Antwort: Ist der ausgewählte Upstream synchron, wartet die Plattform, bis die Generierung abgeschlossen ist, bevor sie den Task zurückgibt. Setzen Sie ein ausreichendes Übermittlungs-Timeout.

Fragen Sie mit derselben Modell-ID ab, die für die Übermittlung verwendet wurde:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Task-Status	Aktion
pending, submitted, processing, in_progress	Warten; nach 3–5 Sekunden erneut abfragen
succeeded, success, completed	Lesen Sie jeden Eintrag in data.result.images; getrackte Tasks verwenden url als Zeichenkette, während ältere Upstream-Antworten ein URL-Array verwenden können
failed, error, cancelled	Beenden Sie das Polling und prüfen Sie den Fehler

Verwenden Sie eine endliche Gesamtfrist für das Polling, etwa 10 Minuten. Läuft diese ab, bewahren Sie die Task-ID für spätere Prüfungen auf, statt automatisch einen weiteren kostenpflichtigen Task zu erstellen. Task-Abfrageantworten und synchrone Bildantworten haben unterschiedliche Strukturen.

Fehlerbehebung bei Referenzbildern

1. Stellen Sie sicher, dass der tatsächliche Anfragepfad /v1/images/edits oder /v1/images/edits/async ist, nicht generations oder generations/async.
2. Stellen Sie sicher, dass die Multipart-Anfrage unter image oder wiederholten image[] Dateibytes enthält, mit einer generierten Boundary. Prompt-Text, Dateinamen und Referenzanzahlen ersetzen keine Dateien.
3. Prüfen Sie die exakte Modell-ID. Eine GPT Image 2-Erweiterung wird von Sunburst oder Flare nicht automatisch unterstützt.
4. Wenn Task-/Protokolldetails keine Vorschau zeigen, schließen Sie nicht daraus, dass kein Bild gesendet wurde: Protokolle können Base64-Daten und hochgeladene Dateiinhalte auslassen. Umgekehrt belegt eine protokollierte Referenzanzahl nicht, dass ein Upstream die Bilder verwendet hat.
5. Testen Sie mit einer einfachen Referenz, die markante Beschriftung oder Formen enthält, und fordern Sie eine Hintergrundänderung an, ohne diese Details zu beschreiben. Vergleichen Sie die Ausgabe visuell.
6. Bewahren Sie für den Support die Anfrage-ID (X-Oneapi-Request-Id), die Task-ID falls vorhanden, Modell, Endpunkt, Zeitstempel, bereinigte Anfragefelder und Referenzbilder auf. Teilen Sie niemals Ihren API-Schlüssel.

Bei einer 400-Antwort prüfen Sie die Endpunkt- und Parameterkompatibilität; 401 zeigt einen Authentifizierungsfehler an; 429 zeigt ein Raten-/Kontingentlimit an. Bei Timeouts oder Upstream-Fehlern bewahren Sie die Anfrage-/Task-ID auf und prüfen den vorhandenen Task oder Nutzungsdatensatz, bevor Sie erneut übermitteln.