Tutorial

So verwendest du flux-2-klein-4b/text-to-image über die hiapi API

Jul 30, 2026

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: So verwendest du flux-2-klein-4b/text-to-image über die hiapi API category: tutorial summary:

Minimales curl- und Python-Beispiel für den Aufruf von flux-2-klein-4b/text-to-image über den einheitlichen /v1/tasks-Endpunkt von hiapi.
'Vollständige Parametertabelle: prompt, aspect_ratio-Enumerationswerte und seed – das strikte Schema lehnt unbekannte Felder ab.'
'Hinweise für den Produktivbetrieb: Abwägung zwischen callback.url und Polling, Idempotency-Key-Header sowie die beiden Fehlerantwort-Strukturen.' takeaways:
Erstelle eine Aufgabe mit POST /v1/tasks und frage dann GET /v1/tasks/{taskId} ab oder empfange das Ergebnis über callback.url.
aspect_ratio unterstützt 11 benannte Seitenverhältnisse; dieses Modell hat kein size- oder n-Feld.
Beim Wiederholen mit demselben Idempotency-Key-Header wird dieselbe taskId zurückgegeben – bei Timeouts sicher wiederverwendbar.
400-Fehler verwenden error_code, 401-Authentifizierungsfehler verwenden das verschachtelte error.code – prüfe zuerst den HTTP-Statuscode. meta_title: flux-2-klein-4b Text-zu-Bild-API-Leitfaden meta_description: 'Aufruf von flux-2-klein-4b/text-to-image mit curl und Python: Aufgabe erstellen, per Polling das Bild abrufen und im Produktivbetrieb Callbacks, Idempotenz und Fehler behandeln.' keywords:
flux-2-klein-4b Text-zu-Bild-API
flux-2-klein-4b API-Beispiel
hiapi Bildgenerierungs-API
flux API curl Python tags:
api-guide
image-generation
flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

So verwendest du flux-2-klein-4b/text-to-image über die hiapi API

Was du baust

Ein Skript, das einen Prompt an flux-2-klein-4b/text-to-image sendet, auf die Bildgenerierung wartet und dann das Bild herunterlädt – dazu die Produktivdetails (Callbacks, Idempotenz, Fehlerstrukturen), die du kennen solltest, bevor du unbeaufsichtigte Läufe startest.

Voraussetzungen: Ein API-Key aus der hiapi-Konsole. Jede Anfrage unten authentifiziert sich mit Authorization: Bearer sk-<your-api-key>.

Minimales lauffähiges Beispiel

Die Generierungsmodelle von hiapi laufen hinter einem einheitlichen asynchronen Endpunkt: POST /v1/tasks erstellt eine Aufgabe und gibt sofort eine taskId zurück; anschließend fragst du GET /v1/tasks/{taskId} ab, bis sie einen Endzustand erreicht.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Rückgabe:

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

Frage dieselbe Aufgabe ab, bis data.status von handling zu success wechselt (dazwischen kurz archiving):

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

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

data.output[0].url ist das fertige Bild. Es ist ein temporärer Link – in Tests läuft er etwa 7 Tage nach der Generierung ab – daher solltest du die Bildbytes herunterladen und selbst speichern, statt direkt auf diese Adresse zu verlinken.

Derselbe Ablauf in Python (mit Polling)

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"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-4b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.jpg", "wb").write(image_bytes)

Wichtige Parameter

flux-2-klein-4b/text-to-image verwendet ein striktes Eingabe-Schema – Felder, die es nicht kennt (size, n, negative_prompt oder was auch immer andere hiapi-Bildmodelle akzeptieren), werden direkt abgelehnt. Kopiere Parameter daher nicht modellübergreifend, ohne vorher die Modellseite zu prüfen.

Feld	Erforderlich	Beschreibung
`prompt`	Ja	Ein String, der das Bild beschreibt.
`aspect_ratio`	Nein	Einer der folgenden Werte: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `21:9`, `9:21`. Bei Auslassung wird standardmäßig `1:1` verwendet.
`seed`	Nein	Ganzzahl. Die Wiederverwendung desselben seed macht die Ergebnisse mehrerer Aufrufe reproduzierbar.

Die vollständige Parameterreferenz findest du auf der Modellseite; den aktuellen Preis pro Bild auf der Preisseite – richte dich nach dieser und nicht nach fest codierten Zahlen, da sich die nutzungsbasierte Abrechnung ändert.

Hinweise für den Produktivbetrieb

Callbacks statt Polling. Außer bei kurzen Skripten solltest du die Polling-Schleife überspringen und im Anfragetext zum Erstellen der Aufgabe callback.url (sowie "when": "final") hinzufügen – nach Abschluss der Aufgabe sendet hiapi das Ergebnis per POST an deinen Endpunkt, mit derselben Nutzlaststruktur wie bei GET /v1/tasks/{taskId}. Details zu Callback-Feldern und Signaturprüfung findest du unter Aufgabe erstellen.

{
  "model": "flux-2-klein-4b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

Idempotenz. Setze im Aufruf von POST /v1/tasks den Header Idempotency-Key (maximal 255 Byte). Wiederholst du dieselbe Anfrage mit demselben Key unter demselben Konto, wird keine zweite Aufgabe erstellt – du erhältst die ursprüngliche taskId zurück. Genau deshalb kannst du Anfragen, die auf deiner Seite in einen Timeout gelaufen sind, sicher wiederholen, ohne doppelt abgerechnet zu werden.

Fehlerbehandlung. In der Praxis treten zwei verschiedene Fehlerstrukturen auf, prüfe daher beide:

Ein fehlerhaftes input (fehlendes prompt, aspect_ratio außerhalb des gültigen Bereichs, nicht unterstützte Felder) liefert HTTP 400 mit dem Antworttext {"error_code": "INVALID_REQUEST", "message": "..."}.
Ein ungültiger oder nicht autorisierter API-Key liefert HTTP 401 mit einer anderen Antwortstruktur: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

Verzweige zuerst anhand des HTTP-Statuscodes und lies dann die tatsächlich vorhandenen Fehlerfelder aus – gehe nicht davon aus, dass alle Fehler dieselbe Antwortstruktur verwenden.

Häufige Fragen

Unterstützt flux-2-klein-4b/text-to-image Bild-zu-Bild? Nicht direkt – dafür gibt es das separate Modell flux-2-klein-4b/image-to-image mit eigenem Eingabe-Schema.

Was ist der Unterschied zwischen flux-2-klein-4b und flux-2-klein-9b? Beide sind Text-zu-Bild-Endpunkte aus derselben FLUX.2-[klein]-Reihe; 9b ist das größere der beiden. Prüfe vor dem Wechsel die Modellseite von 9b auf den aktuellen Preis und die Parameter.

Kann ich in einem Aufruf mehrere Bilder anfordern? Nein – das Schema akzeptiert weder n noch ein Anzahl-Feld. Für jedes Bild ist eine eigene Anfrage nötig.

Wie lange ist die zurückgegebene Bild-URL gültig? output[0].url ist ein temporärer Link mit eigenem expireAt-Zeitstempel; behandle ihn als kurzlebig (in Tests etwa eine Woche) und lade die Bildbytes direkt nach erfolgreichem Abschluss der Aufgabe herunter, statt die URL zu speichern.

Warum erhalte ich einen 401-permission_denied-Fehler? Dein Key fehlt, ist ungültig oder hat keine Berechtigung für dieses Modell. Stelle sicher, dass du Authorization: Bearer sk-... sendest und einen Key aus der Konsole verwendest, keinen Platzhalter.

Muss ich für die Nutzung dieser API einen eigenen Server betreiben? Nur wenn du Callbacks benötigst. Das Abfragen von GET /v1/tasks/{taskId} aus einem Skript, einem Cron-Job oder einer Serverless-Funktion funktioniert bei geringem Traffic problemlos; wechsle zu callback.url, wenn die Generierungsmenge größer wird.