So verwendest du gpt-image-2.5-flare über die hiapi API

gpt-image-2.5-flare ist ein einzelnes Modell auf hiapi, das sowohl die Text-zu-Bild-Generierung als auch die Bildbearbeitung über denselben einheitlichen Endpunkt abwickelt – du brauchst keine separaten Modell-IDs für „Generieren“ und „Bearbeiten“. Diese Anleitung führt dich in wenigen Minuten von null zu einem brauchbaren Bild mit der asynchronen Task-API von hiapi, inklusive vollständigem Node.js-Beispiel und den Produktionsmustern, die du vor dem Go-Live brauchst (Callbacks, Idempotenz, Retries).

Was du benötigst

• Einen hiapi API-Schlüssel. Registriere dich und hole ihn aus dem Dashboard – der Schlüssel hat die Form sk-... und wird im Authorization: Bearer-Header übergeben.
• Einen beliebigen HTTP-Client. Die folgenden Beispiele verwenden Node.js 18+ (mit integriertem fetch), aber dieselben drei Aufrufe lassen sich auch mit curl, Python oder jedem anderen Tool ausführen, das JSON-POST-Anfragen senden kann.

hiapi stellt gpt-image-2.5-flare über dieselbe asynchrone Endpunkt-Familie bereit: Du reichst einen Task ein und fragst dann das Ergebnis ab oder empfängst beim Abschluss einen Webhook-Callback. Es gibt keinen synchronen Aufruf, bei dem du „im Response-Body auf das Bild wartest“ – die Generierung dauert Sekunden, daher ist die API von Anfang an taskbasiert.

Minimales lauffähiges Beispiel (Node.js)

Der folgende Code erstellt einen Task, fragt ihn bis zur Fertigstellung ab und gibt die generierte Bild-URL aus.

const API_KEY = process.env.HIAPI_API_KEY; // sk-...
const BASE = "https://api.hiapi.ai/v1/tasks";

async function createTask(prompt) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      input: {
        prompt,
        aspect_ratio: "16:9",
        quality: "high",
      },
    }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`create task failed (${res.status}): ${JSON.stringify(err)}`);
  }
  const { data } = await res.json();
  return data.taskId; // e.g. "tk-hiapi-..."
}

async function waitForTask(taskId, { timeoutMs = 120_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/${taskId}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` },
    });
    const { data: task } = await res.json();
    if (task.status === "success") return task;
    if (task.status === "fail") {
      throw new Error(`task failed: ${task.error?.code} ${task.error?.message}`);
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

const taskId = await createTask("a minimalist poster of a lighthouse at dawn, flat color");
const task = await waitForTask(taskId);
console.log(task.output[0].url); // download this — it expires, so save it promptly

Ausführen mit HIAPI_API_KEY=sk-... node generate.js. Das data.output-Array im Response erscheint nur, wenn status den Wert "success" hat; jeder Eintrag enthält eine temporäre url (mit expireAt), lade sie also sofort herunter oder lade sie erneut hoch, statt den Link zu speichern.

Wenn du ein vorhandenes Bild bearbeiten statt von Grund auf generieren willst, füge input.image_urls hinzu (Array öffentlich erreichbarer URLs, 1–16 Bilder) und beschreibe im Prompt, was mit jedem Bild geschehen soll – dasselbe Modell, derselbe Endpunkt, keine separate „Bearbeiten“-Modell-ID:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: {
    prompt: "replace the background with a studio gradient, keep the subject unchanged",
    image_urls: ["https://example.com/product-photo.jpg"],
  },
}),

Weitere nützliche input-Felder: background (auto / transparent / opaque, Standard auto) und output_format (png / jpeg / webp, Standard webp). Dieses Modell hat kein resolution-Feld – die Größe wird ausschließlich über aspect_ratio gesteuert (falls du statt eines Seitenverhältnisses exakte Pixelmaße brauchst, akzeptiert es auch explizite Pixelgrößen wie 1536x1024).

Produktionsmuster

Verwende in der Produktion Callbacks statt Polling. Polling eignet sich für Skripte, aber für ein echtes Backend registrierst du einen Webhook, damit hiapi dich in dem Moment benachrichtigt, in dem der Task abgeschlossen ist, statt dass du GET /v1/tasks/<id> in festen Abständen wiederholt abfragst:

body: JSON.stringify({
  model: "gpt-image-2.5-flare",
  input: { prompt: "..." },
  callback: {
    url: "https://yourapp.com/webhooks/hiapi",
    when: "final", // the only supported value — fires once, on success or fail
  },
}),

Dein Webhook-Handler empfängt dasselbe Task-Objekt wie ein Polling mit GET /v1/tasks/<id> – prüfe status und verzweige nach success und fail.

Mach Retries idempotent. Wenn dein Task-Runner fehlgeschlagene HTTP-Aufrufe (Timeouts, 5xx, Netzwerkausfälle) unachtsam wiederholt, kannst du versehentlich zweimal denselben Generierungs-Task einreichen und beide bezahlen. Übergib einen stabilen Idempotency-Key-Header – maximal 255 Byte, üblicherweise deine eigene Task-/Request-ID – dann geben Wiederholungsanfragen mit demselben Key den ursprünglichen Task zurück, statt einen neuen zu erstellen:

headers: {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": jobId, // reuse the same value across retries of the same logical request
},

Behandle spezifische Fehlermodi. Die folgenden Statuscodes solltest du explizit verzweigen, statt in allen Fällen einfach „Retry“ anzunehmen:

Statuscode	Bedeutung	Vorgehen
401 mit error.code: "permission_denied"	API-Schlüssel falsch oder fehlt	Nicht wiederholen – prüfe den Authorization-Header
402	Guthaben reicht nicht aus	Nicht wiederholen – zuerst aufladen
400	Ungültiger Request-Body (falsche Felder, falsche Typen)	Nicht blind wiederholen – korrigiere den Request-Body
503	Vorübergehend nicht verfügbar	Kann sicher mit Backoff wiederholt werden
Task-status: "fail"	Task ist nach der Annahme fehlgeschlagen (z. B. image_urls nicht erreichbar)	Prüfe error.code / error.message, nicht endlos wiederholen

Der 401-Fehler-Response-Body sieht so aus – alle hiapi-Modelle haben dieselbe Form, daher lohnt es sich, das einmal im gemeinsamen Fehlerhandler zu prüfen:

{
  "error": {
    "code": "permission_denied",
    "message": "...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Referenz

• gpt-image-2.5-flare Modellseite – Live-Preise und ein Playground, in dem du Prompts online testen kannst, bevor du sie in Code einbindest.
• Dokumentation der asynchronen Task-API: Task erstellen und Task-Status abrufen – vollständige Feldreferenz für alle Modelle (nicht nur dieses).
• Authentifizierungsdokumentation – wie API-Schlüssel und der Authorization-Header über alle hiapi-Endpunkte hinweg funktionieren.
• Du musst vorhandenen Code von gpt-image-2 migrieren oder möchtest ein Sunburst-spezifisches Bearbeitungs-Tutorial? Siehe den GPT Image 2.5 API-Leitfaden für den Migrationspfad.
• Preise – aktuelle Kosten pro Bild nach Qualitätsstufe (hier nicht kopiert, da sie sich ändern).

Häufige Fragen

Ist gpt-image-2.5-flare ein Modell oder zwei (Generieren + Bearbeiten)? Eins. Ob es generiert oder bearbeitet, hängt allein davon ab, ob du input.image_urls einfügst – kein Wechsel zu einer separaten Modell-ID nötig.

Warum erscheint das Bild nicht sofort im Response? Alle Bildmodelle von hiapi sind asynchron – POST /v1/tasks gibt nur taskId zurück. Du musst GET /v1/tasks/<id> abfragen, bis status den Wert success hat, oder einen callback registrieren, um das tatsächliche output-Array zu erhalten.

Wie lange dauert ein Task? Normalerweise einstellige Sekunden, bei hoher Last gelegentlich länger. Verwende einen großzügigen Polling-Timeout (60–120 Sekunden), statt anzunehmen, dass es immer sofort fertig wird.

Kann ich bei der Bearbeitung mehrere Referenzbilder übergeben? Ja, image_urls akzeptiert bis zu 16 Bilder – erkläre im Prompt, welche Rolle jedes Bild spielt (z. B. „verwende die Pose aus dem ersten Bild mit der Kleidung aus dem zweiten Bild“), denn die Reihenfolge im Array ist wichtig.

Was passiert, wenn meine Callback-URL beim Abschluss des Tasks nicht erreichbar ist? hiapi ruft einmal auf, wenn der Task den finalen Status erreicht (when: "final"). Ist dein Endpunkt nicht erreichbar, erhältst du keine Benachrichtigung – verwende für alles, was nicht verloren gehen darf, Polling als Fallback oder gleiche anhand der von dir gespeicherten Task-ID regelmäßig mit GET /v1/tasks/<id> ab.

Muss ich die Output-URLs selbst speichern? Ja – die url in output[0] ist temporär und läuft ab. Lade sie sofort herunter oder lade sie erneut in deinen eigenen Speicher hoch, sobald der Task erfolgreich war.