Tutorial

So verwenden Sie flux-2-klein-9b/text-to-image über die hiapi API

Jul 30, 2026

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

Minimale curl- und Python-Beispiele für den Aufruf von flux-2-klein-9b/text-to-image über den einheitlichen /v1/tasks-Endpunkt von hiapi.
'Vollständige Parametertabelle: prompt, aspect_ratio, num_inference_steps, output_format und seed – ein striktes Schema lehnt unbekannte Felder ab.'
'Hinweise für den Produktivbetrieb: callback.url im Vergleich zum Polling, der Idempotency-Key-Header sowie die beiden Fehlerantwortstrukturen. takeaways:
Erstellen Sie eine Aufgabe mit POST /v1/tasks und rufen Sie das Ergebnis dann per Polling mit GET /v1/tasks/{taskId} oder über callback.url ab.
num_inference_steps akzeptiert nur 4-8 (Ganzzahl); dieses Modell hat kein Feld size oder n.
Bei Wiederholungen mit demselben Idempotency-Key-Header wird dieselbe taskId zurückgegeben – bei Timeouts kann sie bedenkenlos wiederverwendet werden.
400-Fehler verwenden error_code, 401-Authentifizierungsfehler verwenden das verschachtelte error.code – prüfen Sie zuerst den HTTP-Statuscode. meta_title: flux-2-klein-9b Text-zu-Bild-API-Leitfaden meta_description: Rufen Sie flux-2-klein-9b/text-to-image mit curl und Python auf; erstellen Sie Aufgaben, fragen Sie Bilder per Polling ab und behandeln Sie in der Produktion Callbacks, Idempotenz und Fehler. keywords:
flux-2-klein-9b text-zu-bild api
flux-2-klein-9b api beispiel
hiapi bildgenerierungs-api
flux klein 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 verwenden Sie flux-2-klein-9b/text-to-image über die hiapi API

Was Sie erstellen werden

Ein Skript, das einen Prompt an flux-2-klein-9b/text-to-image sendet, darauf wartet, dass die Bildgenerierung abgeschlossen ist, und das Bild herunterlädt – ergänzt um die Produktionsdetails (Callbacks, Idempotenz, Fehlerstrukturen), die vor unbeaufsichtigten Läufen erforderlich sind.

Voraussetzungen: Rufen Sie einen API-Schlüssel aus der hiapi-Konsole ab. Jede unten stehende Anfrage 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 fragen Sie GET /v1/tasks/{taskId} per Polling 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-9b/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"}

Fragen Sie dieselbe Aufgabe per Polling ab, bis data.status von handling zu success wechselt (dazwischen wird kurz archiving durchlaufen):

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.png", "expireAt": 1785941465}
    ]
  },
  "message": "success"
}

data.output[0].url ist das generierte Bild. Es handelt sich um einen temporären Link – in Tests läuft er etwa 7 Tage nach der Generierung ab –, daher sollten Sie die Bytes herunterladen und selbst speichern, statt direkt auf ihn 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-9b/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.png", "wb").write(image_bytes)

Wichtige Parameter

flux-2-klein-9b/text-to-image hat ein striktes Eingabeschema – Felder, die es nicht kennt (size, n, negative_prompt oder jedes andere Feld, das andere hiapi-Bildmodelle akzeptieren), werden direkt abgelehnt. Kopieren Sie daher keine Parameter zwischen Modellen, ohne vorher die Modellseite zu prüfen.

Feld	Erforderlich	Beschreibung
`prompt`	Ja	Eine Zeichenkette, die das Bild beschreibt.
`aspect_ratio`	Nein	Eines von `1:1`, `4:3`, `3:4`, `16:9`, `9:16`. Standardwert bei Weglassen ist `4:3`.
`num_inference_steps`	Nein	Ganzzahl, 4–8. Standard ist 4; höhere Werte tauschen Geschwindigkeit gegen etwas mehr Detail.
`output_format`	Nein	Eines von `jpeg`, `png`, `webp`. Standard ist `png`.
`seed`	Nein	Ganzzahl. Die Wiederverwendung des Seeds macht die Ergebnisse mehrerer Aufrufe reproduzierbar.

Die vollständige Parameterreferenz finden Sie auf der Modellseite; die aktuellen Preise pro Bild finden Sie auf der Preisseite – prüfen Sie sie dort, statt Zahlen fest zu codieren, da sich nutzungsbasierte Tarife ändern.

Hinweise für den Produktivbetrieb

Verwenden Sie Callbacks statt Polling. Für alles, was über ein schnelles Skript hinausgeht, überspringen Sie die Polling-Schleife und fügen Sie callback.url (sowie "when": "final") in den Anfragetext zur Aufgabenerstellung ein – hiapi sendet das Ergebnis nach Abschluss der Aufgabe per POST an Ihren Endpunkt, wobei die Nutzlaststruktur exakt der von GET /v1/tasks/{taskId} zurückgegebenen entspricht. Einzelheiten zu Callback-Feldern und Signaturprüfung finden Sie unter Aufgabe erstellen.

{
  "model": "flux-2-klein-9b/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. Setzen Sie den Header Idempotency-Key bei Aufrufen von POST /v1/tasks (maximal 255 Byte). Eine Wiederholung derselben Anfrage mit demselben Schlüssel unter demselben Konto erstellt keine zweite Aufgabe – Sie erhalten die ursprüngliche taskId zurück. Genau deshalb können Anfragen, die auf Ihrer Seite ein Timeout erlitten haben, sicher wiederholt werden, ohne doppelt abgerechnet zu werden.

Fehlerbehandlung. In der Praxis treten zwei unterschiedliche Fehlerstrukturen auf, daher sollten Sie beide prüfen:

Fehlerhafte input-Daten (fehlender prompt, num_inference_steps außerhalb des Bereichs, nicht unterstützte Felder) geben HTTP 400 mit {"error_code": "INVALID_REQUEST", "message": "..."} zurück.
Ein ungültiger oder nicht autorisierter API-Schlüssel gibt HTTP 401 mit einer anderen Antwortstruktur zurück: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

Verzweigen Sie zuerst anhand des HTTP-Statuscodes und lesen Sie dann das tatsächlich vorhandene Fehlerfeld – gehen Sie nicht davon aus, dass alle Fehler dieselbe Antwortstruktur verwenden.

Häufige Fragen

Unterstützt flux-2-klein-9b/text-to-image Bild-zu-Bild? Nicht direkt – dafür gibt es ein separates Modell flux-2-klein-9b/image-to-image mit eigenem Eingabeschema.

Was ist der Unterschied zwischen flux-2-klein-9b und flux-2-klein-4b? Beide sind Text-zu-Bild-Endpunkte derselben FLUX.2-[klein]-Reihe; 9b ist das größere der beiden und zielt auf stärkeren Realismus, Textwiedergabe und Detailtreue ab. Prüfen Sie vor einem Wechsel die 4b-Modellseite, um die aktuellen Preise und Parameter zu erfahren.

Kann man in einem Aufruf mehrere Bilder anfordern? Nein – das Schema akzeptiert kein n oder zählendes Feld. Senden Sie für jedes Bild eine eigene Anfrage.

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

Warum erhalte ich einen 401-permission_denied-Fehler? Ihr Schlüssel fehlt, ist ungültig oder hat keinen Zugriff auf dieses Modell. Stellen Sie sicher, dass Sie Authorization: Bearer sk-... mit dem Schlüssel aus der Konsole senden und nicht mit einem Platzhalter.

Muss ich für die Nutzung dieser API einen eigenen Server betreiben? Nur wenn Sie Callbacks benötigen. Das Polling von GET /v1/tasks/{taskId} aus einem Skript, einem Cron-Job oder einer serverlosen Funktion ist bei geringer Nutzung völlig in Ordnung; wechseln Sie zu callback.url, wenn das Generierungsvolumen wächst.