Tutorial

So verwenden Sie gpt-image-2.5-flare@pro über die hiapi-API: curl, Python und eine lauffähige Anfrage

Sep 12, 2026

gpt-image-2.5-flare@pro ist eines der Bildmodelle, die über die einheitliche Task-API von hiapi bereitgestellt werden. Dieser Leitfaden demonstriert zunächst eine minimal lauffähige Anfrage mit curl und Python und stellt dann die für die Produktion erforderlichen Parameter und Muster vor: Callbacks, Idempotenz und Fehlerbehandlung.

Was Sie vorbereiten müssen

Einen hiapi-API-Schlüssel. Sie erhalten ihn in der hiapi-Konsole – jeder Schlüssel beginnt mit sk-.
https://api.hiapi.ai als Basis-URL. Jede Anfrage benötigt den Header Authorization: Bearer sk-<your-key>.

Die Bildgenerierung auf hiapi (sowie alle anderen asynchronen Modelle – Video, TTS, Musik) läuft über denselben Endpunkt: POST /v1/tasks. Sie erstellen zuerst einen Task und können dann entweder GET /v1/tasks/:id abfragen oder einen Callback erhalten, wenn der Task abgeschlossen ist. Die vollständige Referenz finden Sie hier: Einheitliche asynchrone API.

Minimal lauffähiges Beispiel

curl

Task erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare@pro",
    "input": {
      "prompt": "a cyan glass data center entrance, cinematic lighting",
      "aspect_ratio": "16:9",
      "quality": "high",
      "output_format": "png"
    }
  }'

Hier wird eine Task-ID zurückgegeben, kein Bild – die Bildgenerierung ist asynchron:

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

Ergebnis abfragen:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status durchläuft die Reihenfolge queued → handling → archiving → success (oder fail). Wenn der Status success ist, befindet sich das Bild unter data.output[0].url:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "gpt-image-2.5-flare@pro",
    "status": "success",
    "output": [
      { "url": "https://cdn.hiapi.ai/tasks/.../output.png", "type": "image", "expireAt": 1777886899 }
    ]
  }
}

expireAt ist ein Unix-Zeitstempel – laden Sie die Datei vor dessen Ablauf herunter oder hosten Sie sie erneut, denn nach Ablauf funktioniert die URL nicht mehr.

Python

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image_task(prompt: str, aspect_ratio: str = "16:9", quality: str = "high") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "gpt-image-2.5-flare@pro",
            "input": {
                "prompt": prompt,
                "aspect_ratio": aspect_ratio,
                "quality": quality,
                "output_format": "png",
            },
        },
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} did not finish within {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image_task("a cyan glass data center entrance, cinematic lighting")
    result = wait_for_task(task_id)
    if result["status"] == "success":
        image_url = result["output"][0]["url"]
        image_bytes = requests.get(image_url, timeout=30).content
        with open("output.png", "wb") as f:
            f.write(image_bytes)
        print(f"saved output.png from {image_url}")
    else:
        print("task failed:", result.get("error"))

Installieren Sie die einzige Abhängigkeit mit pip install requests, exportieren Sie HIAPI_API_KEY und führen Sie das Skript dann aus.

Wichtige Parameter

gpt-image-2.5-flare bietet zwei Routen: die Standardroute (direkte Verwendung der Modell-ID gpt-image-2.5-flare) und die Pro-Route (Anhängen von @pro, wie in allen obigen Beispielen gezeigt). Es gibt kein explizites Suffix @default – wenn Sie es übergeben, wird MODEL_UNAVAILABLE zurückgegeben.

input akzeptiert die folgenden Felder:

prompt (String, erforderlich) – das einzige Pflichtfeld.
aspect_ratio – 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, auto oder explizite Pixelmaße wie 1536x1024, 2048x2048, 3840x2160.
quality – low, medium, high, xhigh, max oder auto.
output_format – png, jpeg oder webp.
background – auto, transparent oder opaque. In Kombination mit output_format: png oder webp liefert transparent Freistellungsmaterial.

Das Schema ist strikt – unbekannte Felder (size, n oder jedes nicht aufgeführte Feld) führen zu 400 INVALID_REQUEST mit additional properties '<field>' not allowed, statt stillschweigend ignoriert zu werden. Wenn Sie ein vorhandenes Bild bearbeiten statt aus einem leeren Prompt generieren möchten, bietet hiapi dies als separate Modell-ID an – die Bild-zu-Bild-Variante finden Sie auf der Modellseite.

Produktionsmuster

Verwenden Sie Callbacks statt Polling. Fügen Sie der Erstellungsanfrage ein callback-Objekt hinzu:

{
  "model": "gpt-image-2.5-flare@pro",
  "input": { "prompt": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

when: "final" ist derzeit der einzige unterstützte Wert – wenn der Task success oder fail erreicht, sendet hiapi eine einzelne POST-Anfrage an Ihre URL. Der Callback-Body ist identisch mit dem Feld data, das von GET /v1/tasks/:id zurückgegeben wird.

Senden Sie den Header Idempotency-Key. Wenn bei Ihnen eine Anfrage in ein Timeout läuft und wiederholt wird, verhindert der Idempotenzschlüssel, dass hiapi einen zweiten Task für dieselbe Anfrage erstellt (und abrechnet).

Behandeln Sie Fehler explizit. Ein ungültiger oder widerrufener Schlüssel gibt HTTP 401 zurück:

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

Ein fehlerhaftes input gibt HTTP 400 zurück, zusammen mit error_code: "INVALID_REQUEST" und einer message, die das problematische Feld benennt – prüfen Sie diese vor einem erneuten Versuch; ein erneuter Versuch mit demselben Anfrage-Body bei 400 schlägt nur wieder fehl.

Die Preisgestaltung für gpt-image-2.5-flare@pro (Abrechnung pro erfolgreich generiertem Bild, abhängig von Auflösung und Qualitätsstufe) finden Sie auf der Preisseite.

Häufige Fragen

Was ist der Unterschied zwischen der Standardroute und @pro? Es sind zwei eigenständige Routen derselben Modellfamilie, ausgewählt über die von Ihnen gesendete Modell-ID (gpt-image-2.5-flare vs. gpt-image-2.5-flare@pro). Prüfen Sie vor der Wahl die Modellseite und die Preisgestaltung, um die aktuellen Unterschiede bei Kosten und Fähigkeiten zu erfahren.

Kann ich transparente PNGs generieren? Ja – setzen Sie "background": "transparent" zusammen mit "output_format": "png" (oder "webp").

Warum erhalte ich additional properties 'size' not allowed? Das Schema ist strikt. Verwenden Sie aspect_ratio (es akzeptiert auch explizite Pixelmaße wie 1024x1024) statt des Feldes size.

Wie lange ist die Ausgabe-URL gültig? Bis zum Unix-Zeitstempel expireAt im Objekt output[0]. Laden Sie sie vorher herunter oder kopieren Sie sie in Ihren eigenen Speicher – hiapi stellt die Datei danach nicht mehr bereit.

Muss ich noch pollen, wenn ich einen Callback eingerichtet habe? Nein, aber Sie können weiterhin pollen – GET /v1/tasks/:id funktioniert unabhängig davon, ob ein Callback konfiguriert ist, was für eine manuelle Nachprüfung nützlich ist, falls Ihr Callback-Endpunkt eine Zustellung verpasst hat.

Was passiert, wenn meine Anfrage sowohl input_urls als auch einen fehlerhaften prompt enthält? Die Validierung läuft vor der Erstellung des Tasks über den gesamten Anfrage-Body – jedes ungültige Feld (einschließlich fehlerhaft formatierter Medien-Arrays) gibt 400 zurück, und es wird kein Task erstellt (und nichts abgebucht).