So verwenden Sie gpt-image-2/text-to-image über die hiapi API: Parameter, Code und lauffähige Beispiele

Dieses Tutorial zeigt den minimalen Code, der benötigt wird, um mit gpt-image-2/text-to-image über die einheitliche Aufgaben-API von hiapi Bilder zu erzeugen, und erklärt anschließend jeden Parameter sowie die produktionsreifen Muster (Callbacks, Idempotenz, Fehlerbehandlung), die nach dem erfolgreichen Testlauf verwendet werden sollten.

Voraussetzungen

Sie benötigen einen API-Schlüssel. Erstellen Sie ihn auf der Seite für API-Schlüssel in der hiapi-Konsole – der Schlüssel beginnt mit sk-. Die Modellseite von gpt-image-2/text-to-image listet den aktuellen Preis pro Bild auf; die vollständige Aufschlüsselung finden Sie auf der Preisseite.

Alle Aufrufe in dieser Anleitung gehen an den einheitlichen asynchronen Aufgabenendpunkt:

• POST https://api.hiapi.ai/v1/tasks – Erstellt eine Generierungsaufgabe
• GET https://api.hiapi.ai/v1/tasks/{taskId} – Fragt den Aufgabenstatus ab

Die plattformübergreifende Referenzdokumentation finden Sie in der hiapi API-Dokumentation.

Minimales lauffähiges Beispiel (curl)

Eine einzelne Generierung ist eine zweistufige Interaktion: zuerst die Aufgabe erstellen, dann auf ihre Fertigstellung warten.

# 1. Create the task
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/text-to-image",
    "input": {
      "prompt": "a calico cat curled up on a sunlit windowsill, soft focus background",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KVY...."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01KVY...."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

Die Bild-URL befindet sich in data.output[0].url. Laden Sie sie sofort herunter – output[0].expireAt ist sehr kurz, daher dient diese URL nur zum Abrufen, nicht zur dauerhaften Einbettung.

Python: Erstellen + Abfragen + auf Festplatte speichern

import os
import time
import urllib.request
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1K") -> str:
    payload = {
        "model": "gpt-image-2/text-to-image",
        "input": {
            "prompt": prompt,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,
        },
    }
    r = requests.post(API_BASE, json=payload,
                      headers={"Authorization": f"Bearer {TOKEN}"},
                      timeout=60)
    r.raise_for_status()
    body = r.json()
    if body.get("error"):
        raise RuntimeError(f"create failed: {body['error']}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                         headers={"Authorization": f"Bearer {TOKEN}"},
                         timeout=30)
        r.raise_for_status()
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        "a calico cat curled up on a sunlit windowsill, soft focus background",
        aspect_ratio="3:2",
        resolution="1K",
    )
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    urllib.request.urlretrieve(url, "cat.png")
    print(f"saved cat.png from task {task_id}")

Node.js: Derselbe Ablauf mit fetch

// Node 18+ has global fetch
const API_BASE = "https://api.hiapi.ai/v1/tasks";
const TOKEN = process.env.HIAPI_API_KEY;

async function createTask(prompt, aspectRatio = "1:1", resolution = "1K") {
  const res = await fetch(API_BASE, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2/text-to-image",
      input: { prompt, aspect_ratio: aspectRatio, resolution },
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(`create failed: ${body.error.code} ${body.error.message}`);
  return body.data.taskId;
}

async function waitTask(taskId, { timeoutMs = 600_000, pollMs = 5_000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${API_BASE}/${taskId}`, {
      headers: { "Authorization": `Bearer ${TOKEN}` },
    });
    const task = (await res.json()).data || {};
    if (task.status === "success") return task;
    if (task.status === "fail") throw new Error(`task failed: ${JSON.stringify(task.error)}`);
    await new Promise(r => setTimeout(r, pollMs));
  }
  throw new Error(`task ${taskId} timed out`);
}

(async () => {
  const id = await createTask(
    "a calico cat curled up on a sunlit windowsill, soft focus background",
    "16:9",
    "1K",
  );
  const task = await waitTask(id);
  const url = task.output[0].url;
  const img = await fetch(url).then(r => r.arrayBuffer());
  const { writeFileSync } = await import("node:fs");
  writeFileSync("cat.png", Buffer.from(img));
  console.log(`saved cat.png from task ${id}`);
})();

Parameterreferenz

Der Anfragetext enthält immer zwei Felder auf oberster Ebene: model (Zeichenkette, reine Modell-ID gpt-image-2/text-to-image) und input (ein Objekt mit den modellspezifischen Parametern).

input-Feld	Erforderlich	Typ	Beschreibung
prompt	Ja	string	Eine textliche Beschreibung des gewünschten Bildes.
aspect_ratio	Ja	string	Einer der folgenden Werte: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 21:9 oder auto.
resolution	Nein	string	1K (Standard), 2K oder 4K. Die Pixelabmessungen skalieren mit dem gewählten Seitenverhältnis.
callback	Nein	object	{ "url": "https://yours.example/hook", "when": "final" } – siehe nächster Abschnitt.

Eine erfolgreiche Erstellung gibt {"code":200, "data":{"taskId":"tk-hiapi-..."}, "message":"success"} zurück. data.status, zurückgegeben von GET /v1/tasks/{taskId}, ist einer von handling, success oder fail; bei Erfolg ist data.output ein Array, dessen erstes Element die url und den expireAt-Zeitstempel des Bildes enthält.

Andere hiapi-Bildmodelle (z. B. z-image, qwen-image) verwenden etwas andere input-Felder – aspect_ratio ist die Konvention von gpt-image-2/text-to-image. Prüfen Sie beim Modellwechsel die Modellseite, um die genaue input-Struktur zu bestätigen.

Produktionsreife Muster

Callbacks statt Abfragen verwenden

Alle 5 Sekunden abzufragen ist für die Prototypenentwicklung in Ordnung, aber für Produktionsverkehr möchten Sie, dass hiapi fertige Aufgaben an Sie pusht und so Worker freigibt. Fügen Sie einen callback-Block in input hinzu:

{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "an astronaut sketching the moon",
    "aspect_ratio": "3:2",
    "resolution": "1K",
    "callback": {
      "url": "https://your-app.example.com/webhooks/hiapi",
      "when": "final"
    }
  }
}

when: "final" löst genau einmal aus, wenn die Aufgabe einen Endzustand (success oder fail) erreicht. Die Nutzlast, die Ihr Endpunkt empfängt, hat dieselbe Struktur wie GET /v1/tasks/{id}, sodass der Handler die Parsing-Logik der Abfrage wiederverwenden kann. Vergleichen Sie die taskId mit der taskId, die Sie beim Erstellen der Aufgabe gespeichert haben, um zu wissen, zu welcher Anfrage der Callback gehört.

Die Erstellungsoperation idempotent machen

Wenn ein Worker nach POST /v1/tasks, aber vor dem Speichern der taskId abstürzt, könnten Sie dasselbe Bild zweimal generieren. Eine kostengünstige Lösung: Speichern Sie im selben Transaktionskontext, in dem die Anfrage übermittelt wird, (your_request_id → taskId) in der Datenbank in dem Moment, in dem die Erstellungsantwort empfangen wird. Wenn der Worker es erneut versucht, findet er die vorhandene taskId und setzt die Abfrage fort, statt eine neue Aufgabe zu erstellen.

Authentifizierungsfehler korrekt behandeln

hiapi-Authentifizierungsfehler geben HTTP 200 zurück und betten eine Fehlernutzlast in den Antworttext ein:

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. ...","type":"hiapi_error"}}

Ein 200-Statuscode allein bedeutet also nicht Erfolg. Prüfen Sie immer zuerst body.error; falls vorhanden, sehen Sie sich error.code (permission_denied, invalid_request usw.) und error.message an. Die request_id in der Nachricht ist das, was Sie bei Bedarf in ein Support-Ticket einfügen.

Sofort herunterladen und selbst neu hosten

data.output[0].url ist eine kurzlebige URL – die Antwort enthält expireAt. Setzen Sie die hiapi-URL nicht direkt in ein <img src> in Ihrem Produkt; laden Sie den Byte-Stream sofort herunter, sobald die Aufgabe erfolgreich ist, laden Sie ihn in Ihren eigenen Speicher hoch (S3, R2, Supabase Storage usw.) und stellen Sie ihn von dort bereit.

Sinnvolle Timeouts festlegen

Ein sinnvoller Standardwert ist: 60 Sekunden Timeout für die POST-Anfrage (das Erstellen einer Aufgabe ist schnell – Sie warten praktisch nur auf die Bestätigung des Empfangs durch die API), ein Gesamtbudget von 10 Minuten für die Abfrageschleife und ein Abfrageintervall von 5 Sekunden. Aufgaben, die länger als 10 Minuten dauern, bedeuten fast immer, dass die Aufgabe stillschweigend in den Zustand fail übergegangen ist. Daher ist ein Timeout mit Protokollierung des letzten Aufgaben-Antworttexts nützlicher als unendliches Warten.

Häufige Fragen

Was ist der Unterschied zwischen gpt-image-2 und gpt-image-2/text-to-image?

gpt-image-2 ist die Modellfamilie; gpt-image-2/text-to-image ist der spezifische Endpunkt, den Sie aufrufen, um Textaufforderungen in neue Bilder umzuwandeln. Andere Varianten dieser Familie stellen unterschiedliche input-Strukturen bereit (z. B. akzeptiert die Bildbearbeitung Referenzbilder). Verwenden Sie im Zweifelsfall die reine Modell-ID, die Sie auf der Modellseite sehen.

Was bewirkt aspect_ratio: auto?

auto lässt das Modell das Seitenverhältnis anhand der Aufforderung bestimmen. Verwenden Sie es, wenn Sie keine strengen Layoutanforderungen haben; andernfalls legen Sie das Verhältnis selbst fest, damit nachgelagerte Zuschnitte vorhersehbar sind.

Warum gibt meine Anfrage HTTP 200 mit permission_denied zurück?

Entweder ist der API-Schlüssel falsch (Tippfehler, widerrufen, fehlendes sk--Präfix) oder das Paket des Schlüssels enthält gpt-image-2/text-to-image nicht. Öffnen Sie die API-Schlüssel-Konsole, bestätigen Sie die Schlüsselzeichenfolge und prüfen Sie Ihr Paket auf der Preisseite. Prüfen Sie immer body.error.code – verlassen Sie sich nie allein auf den HTTP-Statuscode.

Kann ich mehrere Bilder in einer Anfrage generieren?

gpt-image-2/text-to-image generiert pro Aufgabe nur ein Bild – data.output ist ein Array, hat für dieses Modell aber immer die Länge 1. Um N Varianten zu erzeugen, starten Sie N Aufgaben parallel und verwenden Sie das oben beschriebene callback-Muster, damit Sie nicht N Worker-Threads dauerhaft belegen.

Wie kann ich eine laufende Aufgabe abbrechen?

Die einheitliche Aufgaben-API bietet derzeit keinen Abbruchendpunkt. Die einfachste Abhilfe besteht darin, den Client-Worker das Ergebnis verwerfen zu lassen, wenn der Benutzer es nicht mehr benötigt – die bereits ausgeführte Generierung wird trotzdem abgerechnet, daher liegt der richtige Ort für die Durchsetzung eines Abbruchs vor dem Aufruf von POST /v1/tasks.

Wie wechsle ich zu einem anderen Bildmodell?

Ändern Sie model auf die neue reine ID (z. B. z-image/text-to-image) und passen Sie input an die Struktur dieses Modells an. Die Strukturen unterscheiden sich je nach Modell – einige akzeptieren size, andere aspect_ratio, und einige wenige akzeptieren kein resolution. Der Modellkatalog listet alle verfügbaren Modelle auf, und jede Modellseite dokumentiert ihre input-Felder.