Tutorial

flux-2-klein-9b API: curl- und Python-Leitfaden

Aug 25, 2026

Modell: flux-2-klein-9b

Um auf hiapi mit flux-2-klein-9b ein Bild zu erzeugen, genügt ein einziger POST /v1/tasks-Aufruf plus Polling – genau wie beim asynchronen Task-Muster, das alle Modelle der Plattform verwenden. Dieser Leitfaden dokumentiert eine echte Anfrage samt Antwort (Task-Erstellung, Polling und finale Bild-URL), sodass der folgende Code direkt kopiert und ausgeführt werden kann und kein bloßes Beispiel ist.

Was du vorbereiten musst

Einen hiapi-API-Schlüssel – erstelle ihn in der Konsole. Er wird bei jeder Anfrage als Bearer-Token mitgesendet.
Die vollständige Modell-ID inklusive Endpunkt-Suffix. flux-2-klein-9b ist nur über flux-2-klein-9b/text-to-image erreichbar – ein bloßes flux-2-klein-9b liefert 400 (siehe unten).

Minimale funktionsfähige Anfrage (curl)

Task erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

Antwort:

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

Task bis zum Abschluss pollen:

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

Antwort bei Abschluss:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url ist das PNG. Im Test dauerte es vom Einreichen des Tasks bis zu success etwa 12 Sekunden. Beachte expireAt – lies vor dem Bau jeglicher Funktion, die auf dauerhafte Verfügbarkeit dieser URL angewiesen ist, zuerst den Speicherhinweis unten.

Derselbe Ablauf in Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

Welche Parameter flux-2-klein-9b tatsächlich validiert

Das Input-Schema ist äußerst strikt – sobald ein nicht aufgeführtes Feld gesendet wird, lehnt die API die gesamte Anfrage ab, noch bevor sie in die Warteschlange gelangt:

prompt (String, erforderlich) – das einzige Pflichtfeld.
aspect_ratio (String, optional) – einer der Werte 1:1, 4:3, 3:4, 16:9, 9:16. Jeder andere Wert liefert 400 mit value must be one of ....
seed (Integer, optional) – mit demselben Seed bei identischem Prompt lassen sich reproduzierbare Ergebnisse erzielen.
output_format (String, optional) – einer der Werte jpeg, png, webp.

Das ist das gesamte Schema. Es gibt keine Felder size, quality, strength oder n – das Senden eines davon schlägt fehl:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'size' not allowed"}

flux-2-klein-9b unterstützt ausschließlich Text-zu-Bild. Auch image_urls wird nicht akzeptiert – für Bild-zu-Bild verwende stattdessen die separate Modell-ID flux-2-klein-9b/image-to-image, die eine andere Eingabestruktur annimmt.

Die Modell-ID muss das Endpunkt-Suffix enthalten

Einige Modelle auf hiapi lassen sich mit der reinen ID auflösen (etwa gpt-image-2), flux-2-klein-9b gehört jedoch nicht dazu. Ohne Suffix wird der Task nie erstellt:

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

Sende als model stets den vollständigen String flux-2-klein-9b/text-to-image.

Hinweise für den Produktivbetrieb

Zwei unterschiedliche Fehlerstrukturen. Validierungsfehler (fehlende Felder, falsche Enum-Werte, unbekannte Schlüssel) werden als {"code":400,"error_code":"INVALID_REQUEST","message":"..."} auf oberster Ebene zurückgegeben. Authentifizierungs-/Berechtigungsfehler dagegen als {"error":{"code":"permission_denied","message":"...","request_id":"..."}} – ein verschachteltes error-Objekt mit HTTP 401. Die Fehlerbehandlung sollte beide Strukturen prüfen; Code, der nur resp["code"] prüft, übersieht den 401-Fall.
permission_denied betrifft den Schlüssel, nicht die Anfrage. Wenn prompt vorhanden und vom richtigen Typ ist, aber dennoch 401 permission_denied zurückkommt, wurde dieses Modell für den API-Schlüssel selbst nicht freigeschaltet – prüfe das in der Konsole, anstatt dein JSON wiederholt zu prüfen.
Die Ausgabespeicherung ist temporär. storage: "temp", und jede Ausgabe trägt einen expireAt-Unix-Zeitstempel – im erfassten Beispiel etwa eine Woche nach der Erstellung. Lade die Datei nach einem erfolgreichen Task sofort herunter oder übertrage sie in deinen eigenen Speicher; speichere die URL von temp.hiapi.ai nicht als dauerhafte Adresse.
Für Batch-Tasks Callbacks verwenden. Eine Bildabfrage per Polling ist kein Problem; fünfzig Bilder bedeuten fünfzig wiederholte Roundtrips. Setze auf oberster Ebene der Erstellungsanfrage callback: {"url": "...", "when": "final"}, damit hiapi das Ergebnis einmalig zustellt, wenn der Task tatsächlich abgeschlossen ist. Derzeit unterstützt when nur den Wert "final".
Vor dem Erhalt der taskId wiederholen, nicht danach. Bei Netzwerkfehlern oder 5xx auf das initiale POST /v1/tasks kann sicher erneut versucht werden – zu diesem Zeitpunkt wurde noch nichts erstellt. Sobald du eine taskId hast, erzeugt ein erneutes Senden desselben Prompts ein zweites, unabhängiges Bild; statt dessen solltest du pollen oder auf den Callback warten.

Häufige Fragen

Warum erhalte ich MODEL_UNAVAILABLE, wenn ich flux-2-klein-9b aufrufe? Die Modell-ID benötigt das Endpunkt-Suffix. Verwende flux-2-klein-9b/text-to-image statt der reinen flux-2-klein-9b.

Welche Seitenverhältnisse unterstützt flux-2-klein-9b? Fünf: 1:1, 4:3, 3:4, 16:9, 9:16. Jeder andere Wert liefert 400 mit einer value must be one of-Meldung, die diese fünf Werte auflistet.

Kann ich die Ausgabequalität oder -auflösung steuern? Nein – das Schema akzeptiert nur prompt, aspect_ratio, seed und output_format. Es gibt keine Parameter size oder quality; das Senden eines davon liefert einen 400-Fehler zu additional properties.

Kann ich mit flux-2-klein-9b Bild-zu-Bild-Bearbeitung durchführen? Nicht über diese Modell-ID. Verwende stattdessen flux-2-klein-9b/image-to-image, das ein eigenes Input-Schema hat.

Wie lange ist die Ausgabe-URL gültig? storage ist "temp", und jede Ausgabe trägt einen expireAt-Unix-Zeitstempel, praktisch etwa eine Woche in der Zukunft. Lade die Datei nach einem erfolgreichen Task sofort herunter oder lade sie erneut hoch – behandle die URL nicht als dauerhafte Adresse.

Warum liefert ein Schlüssel, der bei anderen Modellen funktioniert, bei diesem Modell 401? Der Modellzugriff wird pro Schlüssel gewährt. Ein 401 mit error_code: "permission_denied" bedeutet, dass dieser spezifische Schlüssel noch nicht für flux-2-klein-9b autorisiert wurde – aktiviere ihn in der Konsole; das ist kein Fehler in deinem Request-Body.