So verwendest du gpt-image-2.5-sunburst über die hiapi API: curl, Python und funktionierende Request-Beispiele

Um mit gpt-image-2.5-sunburst Bilder zu generieren oder zu bearbeiten, übermittle einen Task mit Prompt an POST /v1/tasks und frage dann GET /v1/tasks/<id> ab (oder empfange einen Callback), bis der Task abgeschlossen ist, und lies die Bild-URL aus data.output[0].url. Dieser Leitfaden behandelt den minimalen Request, den vollständigen Parametersatz sowie die Produktionsmuster (Callbacks, Idempotenz, Fehlerbehandlung), die du vor dem Go-live benötigst.

Voraussetzungen

Du benötigst einen hiapi API-Schlüssel. Erstelle einen im Konsolen-Dashboard – jeder Request authentifiziert sich mit Authorization: Bearer sk-<your-key>. Es gibt keine kostenlose Stufe, um ihn vom Browser aus aufzurufen, und keinen Weg ohne Schlüssel; alle Beispiele unten setzen voraus, dass du bereits einen Schlüssel hast.

Minimal funktionierendes Beispiel

gpt-image-2.5-sunburst/text-to-image benötigt in input nur prompt. Das Seitenverhältnis ist standardmäßig auto, die Auflösung standardmäßig 1K.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "input": {
      "prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter, soft morning light"
    }
  }'

Es wird sofort eine Task-ID zurückgegeben:

{"code":200,"data":{"taskId":"tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ"},"message":"success"}

Ergebnis abfragen:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ \
  -H "Authorization: Bearer sk-<your-key>"

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M23BC5FM0G4N3DN5Y31JF0NZ",
    "status": "success",
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../output-0.webp", "expireAt": 1789571298}
    ]
  }
}

Die Python-Version desselben Round-Trip-Ablaufs:

import time
import requests

API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers=HEADERS,
    json={
        "model": "gpt-image-2.5-sunburst/text-to-image",
        "input": {"prompt": "A minimalist product photo of a ceramic espresso cup on a marble counter"},
    },
    timeout=30,
)
task_id = resp.json()["data"]["taskId"]

while True:
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()
    status = poll["data"]["status"]
    if status in ("success", "fail"):
        break
    time.sleep(2)

if status == "success":
    image_url = poll["data"]["output"][0]["url"]
    print(image_url)
else:
    print("task failed:", poll["data"])

data.output[0].url verweist auf temporären Speicher – die Antwort enthält expireAt (Unix-Sekunden). Lade die Bytes vor dieser Frist herunter und persistiere sie (dein eigener Speicher, S3, R2 usw.); behandle es nicht als permanenten Link.

Vollständige Parameterreferenz

gpt-image-2.5-sunburst hat zwei Modell-IDs: gpt-image-2.5-sunburst/text-to-image für die Generierung aus einem Prompt, gpt-image-2.5-sunburst/image-to-image für die Bearbeitung oder Zusammenführung von Referenzbildern. Beide akzeptieren dieselben Felder; der Unterschied besteht darin, dass image_urls bei image-to-image erforderlich ist, während es bei text-to-image nicht verwendet wird:

Feld	Typ	Standardwert	Beschreibung
prompt	string, 1–8000 Zeichen	—	Erforderlich. Bei Bearbeitungen beschreibe, was geändert werden soll und was exakt unverändert bleiben muss.
image_urls	URL-Array	—	Nur image-to-image, erforderlich, 1–16 JPEG-, PNG- oder WebP-Bilder, jeweils bis zu 20 Megapixel und maximal 30 MB. Muss eine öffentlich herunterladbare URL oder eine data-URI sein.
aspect_ratio	Enum	"auto"	auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, 8:9.
resolution	Enum	"1K"	1K, 2K, 4K. Dies bestimmt den Preis.
background	Enum	keiner	transparent, opaque, auto. transparent wirkt nur bei 1K; in diesem Fall wird ein PNG mit Alpha-Kanal zurückgegeben.

Bearbeitungsbeispiel – übergib ein oder mehrere Referenzbilder und beschreibe nur die gewünschte Änderung:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "input": {
      "prompt": "Change only the ceramic cup color to matte black. Keep the marble counter, lighting, and camera angle exactly as-is.",
      "image_urls": ["https://your-storage.example.com/cup-original.webp"],
      "resolution": "2K"
    }
  }'

Das Schema ist strikt (additionalProperties: false) – unbekannte Felder werden abgelehnt, übernimm daher keine Parameter anderer Bildmodelle (z. B. size, strength, n).

Produktionsmuster

Verwende in einem echten Backend Callbacks statt Polling. Füge einen callback-Block hinzu, um die Polling-Schleife zu überspringen:

{
  "model": "gpt-image-2.5-sunburst/text-to-image",
  "input": {"prompt": "..."},
  "callback": {"url": "https://your-server.example.com/hooks/hiapi", "when": "final"}
}

when: "final" wird genau einmal ausgelöst, wenn der Task einen Endzustand (success oder fail) erreicht. Dein Endpunkt sollte schnell 2xx zurückgeben und die eigentliche Arbeit asynchron erledigen (Ausgabe herunterladen, deine eigene Datenbank aktualisieren) – hiapi wiederholt Callbacks, die keine schnelle Bestätigung erhalten.

Mache Wiederholungen idempotent. Wenn ein Client-Request in eine Zeitüberschreitung läuft, kannst du nicht sicher sein, ob der Task erstellt wurde. Sende im Erstellungs-Request den Header Idempotency-Key (maximal 255 Bytes) und verwende bei Wiederholungen denselben Schlüssel: Mit demselben Konto und Schlüssel wird nur ein Task erstellt, und Wiederholungen geben die ursprüngliche taskId zurück. Ohne ihn wird die wiederholte Verarbeitung desselben Prompts doppelt abgerechnet.

Behandle die Endzustände, auf die du tatsächlich triffst:

• success — lies data.output[0].url und lade zeitnah herunter (beachte expireAt).
• fail — prüfe data.error auf den Fehlergrund, bevor du erneut versuchst; wiederhole nicht blind jeden Fehler, einige sind Probleme auf Prompt-Ebene (z. B. Richtlinienverstöße), die bei unveränderter Wiederholung weiterhin fehlschlagen.
• Das Abfragen einer nicht existierenden Task-ID (Tippfehler, abgelaufen) gibt HTTP 404 mit {"code":404,"message":"task not found"} zurück.

Authentifizierungsfehler sind HTTP 401, keine Fehler auf Task-Ebene:

{"error":{"code":"permission_denied","message":"This API key is invalid...","request_id":"...","type":"hiapi_error"}}

Prüfe dies in deiner Fehlerbehandlung, bevor du einen Task als fehlgeschlagen annimmst – ein ungültiger oder widerrufener Schlüssel gelangt gar nicht erst zur Task-Erstellung.

Weiterführende Lektüre

• GPT Image 2.5 Sunburst Modellseite — Live-Beispiele und aktuelle Preisgestaltung.
• GPT Image 2.5: Generierung, Bearbeitung und Migration — wenn du von einer älteren Image-2-Route auf die 2.5-Serie (Flare oder Sunburst) migrierst, behandelt dieser Artikel die Parameterunterschiede.
• Wie du Bilder mit KI umstilisierst — wenn der Bearbeitungsmodus von Sunburst nur ein Teil deiner Pipeline ist, bietet dieser Artikel eine breitere image-to-image-Durchführung.
• Authentifizierungsdokumentation und Schnellstart für den vollständigen Request-Lebenszyklus über dieses einzelne Modell hinaus.

Häufig gestellte Fragen

Unterstützt gpt-image-2.5-sunburst Bildbearbeitung oder nur Text-zu-Bild? Beides, über zwei Modell-IDs. Verwende gpt-image-2.5-sunburst/image-to-image mit image_urls (1–16 Referenzbilder) für Bearbeitung oder Zusammenführung und gpt-image-2.5-sunburst/text-to-image für die Generierung nur aus Text.

Was passiert, wenn ich ein leeres image_urls-Array sende, anstatt es wegzulassen? Tu das nicht. Bei image-to-image ist image_urls erforderlich und benötigt mindestens eine URL. Für die reine Textgenerierung verwende stattdessen die text-to-image-Modell-ID.

Wie viel kostet ein Bild? Es hängt von resolution ab: 1K kostet $0.05, 2K $0.08, 4K $0.12, gleich für text-to-image und image-to-image. Während der Programmierer-Tag-Aktion (bis 9. November 2026, 00:00 UTC+8) gilt auf alle Stufen 50 % Rabatt: $0.025, $0.04 und $0.06. Prüfe vor dem Skalieren die Modellseite für Live-Preise.

Kann ich feste Pixelmaße anstelle eines Seitenverhältnisses erhalten? Ja – neben Verhältnis-Strings wie 16:9 akzeptiert aspect_ratio auch wörtliche Größen wie 1024x1024, 1536x1024 oder 3840x2160.

Warum erhalte ich 404, wenn ich einen Task abfrage? Entweder enthält die taskId einen Tippfehler, oder der Endpunkt/die Region, die du abfragst, kennt den Task nicht. Prüfe die ID sorgfältig, die du aus der Erstellungsantwort gespeichert hast – hiapi lässt Task-Datensätze in keinem normalen Polling-Fenster stillschweigend verfallen.

Kann ich es zum Testen ohne API-Schlüssel aufrufen? Nein. Jeder /v1/tasks-Request erfordert Authorization: Bearer sk-<key>; es gibt keinen anonymen oder rein browserbasierten Modus.