So verwendest du gpt-image-2.5-sunburst@pro über die hiapi API: curl, Python und ein lauffähiges Anfragebeispiel

gpt-image-2.5-sunburst@pro ist die Pro-Route des Modells gpt-image-2.5-sunburst auf hiapi. Dieser Leitfaden führt dich von Null bis zu einer lauffähigen Anfrage: Was genau die Modell-ID ist, welche exakten input-Felder sie akzeptiert, ein direkt ausführbares curl/Python-Beispiel und die Produktionsmuster, die du vor dem unbeaufsichtigten Betrieb brauchst (Idempotenz, Callbacks, Fehlerbehandlung).

Was du zuerst vorbereiten musst

• Ein hiapi-Konto und einen API-Key aus der Konsole. Jede Anfrage unten authentifiziert sich mit Authorization: Bearer sk-<your key>.
• Das ist alles – keine separate SDK-Installation nötig. Jedes Modell auf hiapi wird über denselben asynchronen Task-Endpunkt aufgerufen, wenn du also zuvor schon ein anderes hiapi-Modell aufgerufen hast, wird dir die Struktur dieser Anfrage vertraut vorkommen.

Das Einzige, was für dieses Modell spezifisch ist: @pro ist ein Routing-Suffix, kein Spitzname. hiapi stellt für manche Modelle mehr als einen Aufrufmodus bereit, und gpt-image-2.5-sunburst ist eines davon – die normale Modell-ID und die ID mit dem Suffix @pro akzeptieren unterschiedliche input-Felder und werden zu unterschiedlichen Preisstufen abgerechnet. Dieser Leitfaden bezieht sich speziell auf gpt-image-2.5-sunburst@pro; mit der bloßen ID gpt-image-2.5-sunburst bekommst du einen anderen Modus und ein anderes Schema (siehe FAQ).

Minimales lauffähiges Beispiel

Jedes Generierungsmodell von hiapi – Bild, Video oder Audio – wird über denselben einheitlichen Endpunkt aufgerufen: POST /v1/tasks. Du übergibst model und input, erhältst sofort eine taskId, und die Generierung läuft asynchron.

Für gpt-image-2.5-sunburst@pro akzeptiert input:

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	1–32.000 Zeichen
image_urls	string[]	Nein	1–16 öffentliche JPEG/PNG/WebP-URLs; mit diesem Feld wird statt Text-zu-Bild Bild-zu-Bild verwendet (SVG wird nicht unterstützt)
aspect_ratio	enum	Nein	z. B. 1:1, 16:9, 9:16 oder explizite Größen wie 1536x1024; Standard 1:1
quality	enum	Nein	low / medium / high / xhigh / max / auto; Standard medium – lies vor dem Erhöhen die Produktionshinweise unten
background	enum	Nein	transparent, opaque oder auto; Standard auto
output_format	enum	Nein	png, jpeg oder webp; Standard webp

curl

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sunburst-pro-demo-001" \
  -d '{
    "model": "gpt-image-2.5-sunburst@pro",
    "input": {
      "prompt": "Ein minimalistisches Produktfoto eines keramischen Pour-over-Kaffeefilters auf einem hellen Holztisch, weiches Studiolicht",
      "aspect_ratio": "1:1",
      "quality": "medium",
      "output_format": "webp"
    }
  }'

Dies gibt sofort eine taskId zurück:

{ "code": 0, "message": "ok", "data": { "taskId": "task_xxxxxxxx" } }

Dann fragst du das Ergebnis per Polling ab:

curl -s "https://api.hiapi.ai/v1/tasks/task_xxxxxxxx" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Sobald data.status gleich success ist, befindet sich das Bild unter data.output[0].url.Lade es sofort herunter – die URL hat ein expireAt und eignet sich nicht für dauerhafte externe Verlinkung.

Python

import time
import requests

API_KEY = "sk-YOUR_API_KEY"
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def submit_task():
    payload = {
        "model": "gpt-image-2.5-sunburst@pro",
        "input": {
            "prompt": "Ein minimalistisches Produktfoto eines keramischen Pour-over-Kaffeefilters "
                      "auf einem hellen Holztisch, weiches Studiolicht",
            "aspect_ratio": "1:1",
            "quality": "medium",
            "output_format": "webp",
        },
    }
    r = requests.post(
        f"{BASE}/tasks",
        headers={**HEADERS, "Idempotency-Key": "sunburst-pro-demo-001"},
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def poll_task(task_id, timeout_s=180, interval_s=3):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data.get('error')}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = submit_task()
    image_url = poll_task(task_id)
    print("image ready:", image_url)

Produktionsmuster

Polling und Callbacks. Die obige Schleife ist für Skripte und geringen Datenverkehr in Ordnung. Für jedes serverseitige Szenario bevorzuge Callbacks statt Polling: Füge in derselben Anfrage ein callback-Objekt hinzu –

{
  "model": "gpt-image-2.5-sunburst@pro",
  "input": { "...": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

callback.url muss HTTPS sein; when: "final" (der derzeit einzige unterstützte Wert) benachrichtigt dich sowohl bei Erfolg als auch bei Fehler genau einmal – keine Polling-Schleife, keine verschwendeten Anfragen. hiapi kann Callbacks mehrfach zustellen, deshalb solltest du auf deiner Seite nach taskId deduplizieren.

Idempotenz. Füge bei POST /v1/tasks den Header Idempotency-Key hinzu (eine beliebige Zeichenkette bis 255 Byte, z. B. eine Bestell-ID). Wenn ein Netzwerk-Timeout dazu führt, dass dein Client dieselbe Übermittlung erneut versucht, gibt die Plattform die ursprüngliche taskId zurück (Antwort-Header Idempotent-Replay: true), statt einen zweiten Task zu erstellen – und zu berechnen. Der Key gilt innerhalb deines Kontos und läuft nach 24 Stunden ab; wenn du ihn mit einem anderen Request-Body wiederverwendest, erhältst du 422 IDEMPOTENCY_KEY_MISMATCH, statt dass stillschweigend ein neuer Task erstellt wird – eine Nichtübereinstimmung ist also ein Signal, deine Retry-Logik zu prüfen, statt blind zu wiederholen.

Authentifizierungsfehler. Ein fehlerhaft formatiert oder falscher API-Key schlägt schnell fehl, mit 401 und dem Fehlercode permission_denied, noch bevor irgendein Task erstellt wird:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Wenn du das siehst, liegt die Ursache fast immer beim Key selbst (falsch gesetzte Umgebungsvariable, abgelaufener Key, fehlendes sk--Präfix) – nicht im Request-Body. Behandle ihn als nicht wiederholbar, bis der Key korrigiert ist.

Zu quality. quality ist standardmäßig medium, ein sinnvoller Standardwert für den Start – eine Erhöhung steigert sowohl Kosten als auch Generierungszeit, also erhöhe nur dann auf high/xhigh/max, wenn du in deinen eigenen Tests bestätigt hast, dass ein gegebener Prompt auf dieser Stufe noch zuverlässig erfolgreich ist.

Verwandte Seiten

• gpt-image-2.5-sunburst Modellseite – Fähigkeiten der Modellfamilie, Beispielausgaben und alle verfügbaren Modi.
• Dokumentation der einheitlichen asynchronen API – der vollständige /v1/tasks-Vertrag, den alle hiapi-Generierungsmodelle teilen (Idempotenz, Callbacks, Statuscodes).
• Authentifizierungsdokumentation – wie du API-Keys erstellst und verwaltest.
• gpt-image-2.5-sunburst API-Leitfaden – wenn du den Basis-Modus (ohne @pro) möchtest, beschreibt dieser Artikel ausführlich dessen eigenständiges, auf resolution basierendes Schema.
• Preise – aktuelle Kosten pro Bild je quality-Stufe.

FAQ

Sind gpt-image-2.5-sunburst@pro und gpt-image-2.5-sunburst unterschiedliche Modelle? Es ist dieselbe Modellfamilie, aber eine andere Route. Die bloße ID gpt-image-2.5-sunburst (und ihr /text-to-image-Modus) akzeptiert ein resolution-Feld (1K/2K/4K) und hat keine Felder quality oder image_urls. @pro ersetzt dies durch quality-Stufen und fügt optionale image_urls hinzu; verwende also diese Route, wenn du in demselben Aufruf die Qualitätsstufe steuern oder Bild-zu-Bild nutzen möchtest.

Brauche ich ein Referenzbild? Nein. Bei Text-zu-Bild lässt du image_urls einfach ganz weg. Mit 1–16 öffentlichen Bild-URLs wird die Ausgabe stattdessen anhand von Referenzbildern konditioniert.

Kann ich dieses Modell ohne API-Key verwenden? Nein – jede Anfrage benötigt einen gültigen Authorization: Bearer-Header mit einem echten hiapi API-Key deines Kontos. Es gibt keine nicht authentifizierte oder key-freie Stufe.

Was kostet das? Die Preise variieren je nach quality-Stufe und werden auf der Preisseite aktuell gehalten, statt hier wiederholt – schau dort nach, bevor du Kosten für große Mengen schätzt.

Was, wenn mein Callback nie ankommt? Die Callback-Zustellung ist nicht sofort garantiert, und hiapi kann Zustellungen wiederholen (dedupliziere daher nach taskId). Wenn du eine harte Obergrenze brauchst, behalte nach dem Timeout ein Ausweich-Polling auf GET /v1/tasks/:id bei, statt unbegrenzt auf den Callback zu warten.

Warum erhalte ich den Status fail statt eines Fehlers bei der Übermittlung? Die Übermittlung (die 200/taskId zurückgibt) bedeutet nur, dass die Anfrage akzeptiert wurde – die Generierung selbst kann asynchron fehlschlagen. Prüfe nach dem Polling oder über den Callback data.status und schaue vor dem erneuten Übermitteln in data.error nach der Ursache.