GPT Image 2.5 API-Integration: Generieren, Bearbeiten und Migration von Image 2

Um GPT Image 2.5 in HiAPI zu integrieren, wählen Sie zunächst gpt-image-2.5-flare oder gpt-image-2.5-sunburst und reichen Sie dann die Aufgabe über POST /v1/tasks ein. Beide Modelle unterstützen Generierung und Bearbeitung; ob image_urls übergeben wird, entscheidet darüber, ob die Anfrage Referenzbilder enthält.

Bei der Migration von Image 2 müssen sowohl der Modellname als auch die Eingabeparameter geändert werden. Die älteren Versionen von resolution, size, dem Referenzbildfeld und den Routeneinstellungen haben unterschiedliche Konventionen. Wenn nur eine Modellzeichenkette ersetzt wird, bleiben leicht unpassende Parameter zurück.

Der folgende Code wurde nach der HiAPI-Onlinedokumentation vom 9. September 2026 verfasst und dient zur Erläuterung des Anfrage- und Asynchronverarbeitungsablaufs. Tatsächliche Ausgaben und Kosten richten sich nach dem Aufgabenprotokoll. Parameteraktualisierungen richten sich nach der Flare-Dokumentation und der Sunburst-Dokumentation.

Eine Modell-ID für Generierung und Bearbeitung

Flare und Sunburst haben in HiAPI dieselben Anfragefelder. Nach Auswahl eines Modells lassen Sie bei der reinen Textgenerierung image_urls weg; bei der Bearbeitung fügen Sie 1–16 Referenzbilder hinzu und geben im Prompt an, was geändert und was beibehalten werden soll. Senden Sie für die reine Textgenerierung kein leeres Array und hängen Sie auch nicht selbst die Suffixe /edit oder /text-to-image an. Jede Aufgabe gibt ein Bild aus.

Wenn Sie bereits einen stabilen Bild-Workflow haben, können Sie zunächst eine Aufgabenart migrieren und die ursprünglichen Eingaben und Abnahmekriterien beibehalten. Zur Positionierung der beiden Modelle lesen Sie zunächst die Unterschiede zwischen Image 2 und 2.5; dieser Artikel konzentriert sich darauf, wie die Anfrage umgesetzt wird.

Eine Generierungsanfrage einreichen

Das folgende Beispiel generiert ein quadratisches Produktbild einer Tasse. Speichern Sie das JSON als request.json. quality wird explizit auf medium gesetzt, um die Parameter später reproduzieren zu können; aspect_ratio wird auf die in der Dokumentation aufgeführte Pixelgröße 1024x1024 gesetzt.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Der API Key wird in der serverseitigen Umgebungsvariable HIAPI_API_KEY abgelegt. Der folgende Befehl liest die Datei ein, reicht sie ein und speichert die Antwort der Aufgabenerstellung. HIAPI_REQUEST_ID wird von Ihrer Anwendung für diese logische Anfrage generiert; bei einem Netzwerkproblem wird sie bei einem erneuten Versuch derselben Anfrage wiederverwendet, bei geänderten Eingaben oder der Erstellung eines weiteren Bildes wird ein neuer Wert verwendet.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

Nach erfolgreicher Erstellung lesen Sie die Aufgaben-ID aus data.taskId in created.json. Das Bild wird zu diesem Zeitpunkt noch asynchron generiert. Idempotency-Key dient dazu, zu vermeiden, dass dieselbe logische Anfrage durch wiederholtes Einreichen mehrere Aufgaben erzeugt; die vollständigen Konventionen finden Sie in der Dokumentation zum Erstellen von Aufgaben. Betrachten Sie eine erfolgreiche Einreichung nicht als abgeschlossenes Bild.

Bilder mit derselben Schnittstelle bearbeiten

Im Folgenden eine eigenständige Sunburst-Bearbeitungsanfrage. Ersetzen Sie die Platzhalteradresse in image_urls durch eine echte Referenzbild-URL, die der Dienst lesen kann, speichern Sie sie als request.json und reichen Sie sie mit einer neuen Anfrage-ID ein. Die example.com-Adresse veranschaulicht nur die Feldstruktur und kann nicht direkt zur Generierung verwendet werden.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Bei mehreren Referenzbildern erläutern Sie den Zweck in der Reihenfolge des Arrays, z. B. liefert das erste Bild das Produkt und das zweite den Hintergrund. Bei aufeinanderfolgenden Änderungen verwenden Sie die im vorherigen Schritt gespeicherte Ausgabe als Referenzbild für die nächste Anfrage; jede ist weiterhin eine neue Aufgabe, für die neue Änderungsanforderungen klar angegeben werden müssen. Gehen Sie nicht davon aus, dass die Schnittstelle automatisch den vorherigen Dialog oder das vorherige Bild beibehält.

Für einen transparenten Hintergrund setzen Sie background auf transparent und wählen PNG oder WebP. JPEG unterstützt keinen Transparenzkanal. Prüfen Sie nach der Modellausgabe weiterhin Ränder und Motiv; Feldeinstellungen ersetzen keine Bildabnahme.

Status abfragen, dann Datei speichern

GET /v1/tasks/:id liefert die Aufgabendetails. queued, handling und archiving sind alle nicht terminal; nur success bedeutet, dass die Ausgabe verwendbar ist, fail liefert über data.error Fehlerinformationen. Das äußere code: 200 bedeutet nur, dass die Abfrage erfolgreich war; Sie müssen weiterhin data.status auswerten. Dokumentation zu Aufgabendetails

Das folgende Python-Beispiel verwendet requests, liest die zuvor erstellte created.json, wartet zunächst 3 Sekunden und fragt dann alle 4 Sekunden ab. Es speichert das Detail-JSON und das erste Bild. 10 Minuten sind die lokale Warteobergrenze des Beispiels; sie stellen weder eine SLA des Dienstes dar noch brechen sie die serverseitige Aufgabe ab. Nach dem Timeout behalten Sie die taskId und fragen später dieselbe Aufgabe weiter ab.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Temporäre Ausgaben müssen vor output[].expireAt heruntergeladen oder übertragen werden. Für den Produktivbetrieb kann auf der obersten Ebene der Anfrage ein callback konfiguriert werden, um Benachrichtigungen über den Endzustand zu erhalten, wobei Polling als Fallback beibehalten wird; die Callback-Felder dürfen nicht in input abgelegt werden. Die Verifikation von Callbacks und die Behandlung doppelter Benachrichtigungen erfolgen gemäß der einheitlichen asynchronen API. Das Beispiel enthält keine Geschäfts-Warteschlange, keinen Callback-Dienst und keine vollständige Netzwerk-Retry-Strategie.

Migration von Image 2: Eingaben Punkt für Punkt prüfen

Die ältere Version von Image 2 hatte andere Routen; bestätigen Sie bei der Migration zunächst, welche aktuell verwendet wird. Die folgende Liste zeigt die Parameterunterschiede zwischen den HiAPI-Dokumentationen und gilt nicht dafür, SDK-Anfragen anderer Anbieter unverändert zu übernehmen.

Alter Workflow	Anpassung bei Image 2.5
Generierung und Bearbeitung verwenden unterschiedliche Image 2-Modell-IDs	Verwenden Sie stattdessen die vollständigen Flare- oder Sunburst-IDs; unterscheiden Sie durch das Vorhandensein oder Fehlen von image_urls
Standard-Bearbeitung verwendet input_urls	Ändern Sie zu image_urls; die alte ext-Bearbeitung hat dieses Feld bereits verwendet
Standard / ext verwendet resolution	Wählen Sie je nach Zielgröße erneut das Verhältnis oder die Pixel-Enumeration in aspect_ratio; behalten Sie resolution nicht bei
Beta-Generierung verwendet size	Ändern Sie zu der in der Dokumentation unterstützten aspect_ratio-Pixel-Enumeration; kopieren Sie nicht beliebige Größen unverändert
Explizites route: "beta" / "ext" oder Modellname mit Routen-Suffix	Rekonstruieren Sie die Anfrage gemäß der 2.5-Modelldokumentation; übernehmen Sie die alten Routen nicht
Von der alten Version unterstützte Verhältnisse wie 4:5	Punkt für Punkt prüfen; die aktuelle Enumeration von 2.5 enthält kein 4:5; ändern Sie es nicht stillschweigend in ein anderes Verhältnis
Verlass auf Standardqualität, -größe oder -ausgabeformat	Explizit angeben und Ausgabe, Kosten und nachgelagerte Dateiverarbeitung erneut prüfen

Die aktuellen Verhältnisoptionen von 2.5 sind 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 und auto. Darüber hinaus akzeptiert aspect_ratio die 10 in der Dokumentation aufgeführten Pixelgrößen. Wenn Sie eine feste Größe benötigen, wählen Sie einen Enumerationswert; schließen Sie nicht allein aus dem Zeichenkettenformat, dass jedes beliebige widthxheight verfügbar ist. Insbesondere bei auto beschreibt die neue Dokumentation, dass das Modell eine passende Komposition wählt; übernehmen Sie nicht direkt die Annahme der alten Bearbeitungsroute „folgt dem Eingabebild“.

Die Qualitätsoptionen sind low, medium, high, xhigh, max, auto, Standard ist medium. Gleichnamige Qualitätsstufen garantieren nicht dieselben Kosten oder dieselbe visuelle Leistung wie bei älteren Modellen. Das vollständige alte Protokoll kann mit der Image 2-Generierung und der Image 2-Bearbeitung Dokumentation abgeglichen werden.

Fehler und Budget in derselben Abnahmekette

Bei der Einreichung sollten Sie bei 400 Modellnamen, Felder und Enumerationen prüfen; bei 402 den Kontostand; bei 415 den Content-Type. Wenn nach der Aufgabenerstellung fail auftritt, speichern Sie data.error zur Fehlersuche und reichen Sie dieselbe ungültige Eingabe nicht erneut ein. Bei 503 können Sie später mit Backoff erneut versuchen; wenn bei einer POST-Anfrage aufgrund einer Netzwerkunterbrechung nicht feststellbar ist, ob sie erstellt wurde, verwenden Sie den ursprünglichen Idempotenzschlüssel, um doppelte Aufgaben zu vermeiden. Fehlerbeschreibung bei der Aufgabenerstellung

Die Kostenprüfung beginnt mit der aktuellen Preisseite von HiAPI und der jeweiligen Modellseite. Bei der Migrationsabnahme erfassen Sie vollständigen Modellnamen, Größe, Qualität, Anzahl der Referenzbilder, Anfrage, Ausgabe und tatsächliche Abrechnung; übernehmen Sie nicht den Stückpreis des alten Image 2 und betrachten Sie nicht die Einstiegspreise anderer Plattformen als HiAPI-Angebot. Beispielbilder auf der Website können bei der Bewertung der Ergebnisse helfen; API-Laufzeit und Abrechnung erfordern jeweils eigene tatsächliche Aufzeichnungen.

Nachdem Sie eine Generierungsaufgabe und eine Bearbeitungsaufgabe integriert, gespeichert und abgenommen haben, erweitern Sie auf Batch-Prozesse. Den aktuellen Einstiegspunkt finden Sie auf der Flare-Modellseite oder der Sunburst-Modellseite; pflegen Sie die Parameter anschließend gemäß der jeweiligen Docs.