Tutorial
So verwendest du flux-3 über die HiAPI API: curl, Python und lauffähige Request-Beispiele
Auf dieser Seite
Was du durch die Nutzung von flux-3 über HiAPI gewinnst
flux-3 ist ein Bildgenerierungsmodell, das sowohl Text-zu-Bild als auch Bild-zu-Bild beherrscht. Wenn du Produktfunktionen, Design-Tools oder interne Pipelines baust, ist der wirklich interessante Teil oft nicht das Modell selbst – sondern wie sauber du es hinter eine stabile, vorhersehbare Schnittstelle bringen und diesen Zustand bei sich ändernden Anforderungen aufrechterhalten kannst.
Genau hier liegt der Wert einer aggregierenden API-Plattform. flux-3 über HiAPI aufzurufen bedeutet für dich:
- Nur einmal integrieren. Eine einzige Basis-URL, eine einzige Authentifizierungsmethode und eine konsistente Request- und Response-Struktur über alle Modelle hinweg, die du verwendest. Ein Modellwechsel oder -vergleich ist danach nur eine Konfigurationsänderung statt einer Code-Neuschreibung.
- Infrastrukturarbeit entfällt. Kein Hosten von Modellen, keine GPU-Kapazitätsplanung, kein Cold-Start-Management auf deiner Seite. Du sendest eine HTTP-Anfrage und verarbeitest die Antwort.
- Zentrale Verwaltung der Zugangsdaten. Nur ein API-Key zum Ausstellen, Rotieren und Einschränken, statt separater Beziehungen zu jedem Upstream-Anbieter.
- Einheitliche Fehlersemantik. Statuscodes und Fehler-Wrapper sind gleich, egal welches Modell hinter dem Aufruf steht – das macht Retry- und Alerting-Logik wiederverwendbar.
Konkret für flux-3 heißt das: Du kannst vom Prototyp im Notebook direkt zum Produktions-Endpunkt wechseln, ohne die Struktur deines Client-Codes zu ändern. Beide Generierungsmodi – Text-zu-Bild und Bild-zu-Bild – teilen dieselbe Request-Struktur, sodass die Unterstützung beider nur davon abhängt, welche Felder du befüllst, nicht davon, welches SDK du importierst.
In diesem Artikel gelten folgende Konventionen:
- Basis-URL: der HiAPI-API-Endpunkt, der in deiner Konto-Konsole hinterlegt ist.
- Authentifizierung: Bearer-Token im
Authorization-Header. - Content-Typ:
application/jsonfür den Request-Body; Bildeingaben je nach Größenbeschränkung deiner Payload als URL oder base64-kodierte Daten.
Halte Schlüssel in Umgebungsvariablen – niemals in der Versionsverwaltung committen. Die folgenden Beispiele lesen den Schlüssel aus HIAPI_API_KEY und die Modellkennung aus FLUX_MODEL, sodass du ohne Codeänderungen anpassen kannst.
Nach dieser Vorbereitung zerlegt der nächste Abschnitt den Request-Body selbst.
Anatomie einer Anfrage: Text-zu-Bild und Bild-zu-Bild
Ein flux-3-Aufruf gliedert sich logisch in drei Teile: den Endpunkt-Pfad, die Autorisierungs-Header und einen JSON-Request-Body. Der Request-Body ist der Ort, an dem sich die beiden Modi unterscheiden – und wenn du diesen Unterschied verstehst, kannst du einen Client für beide wiederverwenden.
Gemeinsames Gerüst
Jede Anfrage enthält Felder in etwa dieser Form:
- model – das aufzurufende Modell; hier deine flux-3-Kennung.
- input – das Objekt, das die Generierungsanweisungen trägt.
- input.prompt – die natürlichsprachliche Beschreibung dessen, was du willst. In beiden Modi Pflicht.
- Optionale Generierungseinstellungen – etwa Ausgabegröße, Seitenverhältnis oder Schritte, abhängig von den Fähigkeiten des Modells. Setze nur, was du brauchst; die Standardwerte sind meist vernünftig.
- Optionale asynchrone Steuerung – Flags oder Callbacks, die ändern, wie eine Aufgabe ausgeführt und ausgeliefert wird (Details im nächsten Abschnitt).
Text-zu-Bild
Im Text-zu-Bild-Modus ist prompt das einzig wesentliche Feld. Du beschreibst das Bild, schränkst optional die Ausgabegeometrie ein und reichst ein. Es gibt kein Quellbild, also hat das Modell maximale Freiheit – was auch bedeutet, dass die Prompt-Qualität die Ausgabequalität dominiert.
Eine nützliche Gewohnheit: Schreibe Prompts so, als würdest du einem menschlichen Illustrator ein Briefing geben. Beschreibe in der Reihenfolge Motiv, Komposition, Beleuchtung, Stil und harte Vorgaben (z. B. „kein Text im Bild“, „Motiv zentriert“). Vage Prompts liefern egal bei wie vielen Schritten mittelmäßige Ergebnisse.
Bild-zu-Bild
Im Bild-zu-Bild-Modus fügst du zusätzlich zum Prompt ein Quellbild-Feld hinzu, und der Prompt beschreibt dann eine Transformation relativ zu dieser Eingabe statt eine von Grund auf konstruierte Szene. Je nach Modell-Schnittstelle kann das bedeuten, eine Bild-URL oder eine kodierte Payload bereitzustellen, plus etwaige Stärke- oder Guidance-Parameter, die steuern, wie weit die Ausgabe vom Quellbild abweicht.
Für deinen API-Client ist der praktische Unterschied gering: gleicher Endpunkt, gleiche Authentifizierung, gleiches input-Objekt – nur ein Feld mehr. Genau das ist das Designziel. Deine generate()-Funktion sollte ein optionales Quellbild akzeptieren und die Verzweigung intern behandeln, sodass Aufrufer nie wissen müssen, welchen Modus sie ausgelöst haben.
Antwortstruktur
Die Antwort sollte eine Aufgabenkennung enthalten und bei Abschluss den Ort des generierten Bildes mitbringen. Behandle diesen Ort als undurchsichtigen Wert: abrufen oder speichern ja, aber keine Annahmen über den Inhalt anstellen. Manche Antworten kommen sofort zurück, andere sind Task-Handles – genau deshalb muss asynchrone Verarbeitung vom ersten Tag an in das Design einfließen.
Parameter und asynchrone Modi
Generierungseinstellungen wählen
Generierungseinstellungen sind ein Abwägen zwischen Qualität, Latenz und Kosten. Folgende Prinzipien gelten für die meisten Bildmodelle, auch für flux-3:
- Auflösung und Seitenverhältnis beeinflussen sowohl die Nützlichkeit der Ausgabe als auch den Rechenaufwand. Generiere in der Größe, in der du tatsächlich auslieferst; ein großes Bild zu verkleinern verschwendet Budget, ein kleines hochzuskalieren verschwendet Rendering.
- Schritte oder Qualitätskontrolle steigern die Treue nur bis zu einem Punkt und flachen dann ab. Ermittle diesen Knickpunkt mit einem festen Prompt durch Messungen und bleib dort.
- Determinismus-Kontrollen (falls verfügbar) sind wichtig für Reproduzierbarkeit. Wenn du für QA oder Nutzersupport dasselbe Ergebnis erneut rendern musst, protokolliere die Einstellungen zusammen mit der Ausgabe.
Rate keine Parameternamen oder zulässigen Bereiche – lies sie aus der Modelldokumentation in der Konsole und halte dich daran. Wenn ein Feld abgelehnt wird, sagt dir die Fehlerantwort genau, welches.
Synchron vs. asynchron
Bildgenerierung ist keine sofortige Operation. Es gibt zwei Ausführungsmodi:
Synchron (blockierend). Du sendest die Anfrage und hältst die Verbindung offen, bis das Bild fertig ist. Das ist einfach und geeignet für kurze Aufgaben, Skripte und interaktive Tools, bei denen Nutzer auf eine Ladeanimation schauen. Es ist aber auch fragil: Serverless-Funktionen, Load-Balancer und mobile Clients haben Timeouts, und langes Rendering trifft zwangsläufig eines davon.
Asynchron (aufgabenbasiert). Du reichst die Anfrage ein, erhältst sofort eine Kennung und pollst dann einen Status-Endpunkt oder empfängst einen Callback, bis die Aufgabe den Abschluss meldet. Wähle diesen Modus in folgenden Fällen:
- Serverless- und Edge-Runtimes mit harten Ausführungszeitlimits.
- Batch-Jobs, die viele Renderings parallel einreichen müssen.
- Jeder Interaktionsfluss, der die Kontrolle sofort zurückgeben und Fortschritt streamen soll.
Entwirf den Client um Asynchronität herum und wickle einfache Fälle mit einer synchronen Komfortmethode ab. Das Gegenteil – Asynchronität in einen blockierenden Client hineinzwängen – endet selten gut.
Beim Polling nutze begrenztes exponentielles Backoff statt einer engen festen Schleife, setze eine Obergrenze für die Gesamtwartezeit und behandle Aufgaben, die nie einen Endzustand erreichen, als alarmwürdigen Fehler.
Ein lauffähiger curl-Request
Beginne im Terminal; sobald der rohe HTTP-Austausch klar ist, sind die Code-Versionen einfach.
1. Umgebung einrichten
export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"
Lege die Modellkennung in eine Variable – ein späterer Modellwechsel ist dann eine Zeile.
2. Text-zu-Bild-Request senden
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Eine minimalistische Studioaufnahme einer Keramiktasse auf einer Betonfläche, weiches Seitenlicht, geringe Schärfentiefe"
}
}'
Das -sS-Flag hält die Ausgabe sauber und zeigt dennoch Fehler. Prüfe vor dem Ausführen den genauen Pfad gegen den in deiner Konsole hinterlegten Endpunkt – Pfade sind versioniert, die Dokumentation ist maßgeblich.
3. Rückgabe lesen
Pipe die Antwort durch einen Formatierer, damit sie lesbar ist:
... | python -m json.tool
Achte auf zwei Dinge: die Aufgabenkennung und den Bildort oder ein Statusfeld, das dir sagt, dass die Aufgabe noch läuft. Wenn du einen Status statt eines Bildes siehst, bist du auf dem asynchronen Pfad – notiere die Kennung und wechsle zum Polling.
4. Bild-zu-Bild ausprobieren
Füge das Quellbild in das input-Objekt ein, alles andere bleibt gleich:
curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLUX_MODEL"'",
"input": {
"prompt": "Als Aquarell neu interpretieren, Komposition und Schatten intakt lassen",
"image": "https://example.com/source.jpg"
}
}'
Da sich die Anfrage nur um ein Feld unterscheidet, hat dein erster erfolgreicher Aufruf bereits den Großteil der Integration validiert. Der Rest – Retries, Speicherung, UI – ist gewöhnliche Anwendungsarbeit.
Derselbe Request in Python
Der curl-Aufruf lässt sich direkt übertragen. Im Folgenden ein kleiner wiederverwendbarer Client statt eines Wegwerf-Skripts.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def generate(prompt, image=None, timeout=60):
"""Reicht einen flux-3-Generierungsjob ein. Übergib image= für Bild-zu-Bild."""
payload = {"model": MODEL, "input": {"prompt": prompt}}
if image:
payload["input"]["image"] = image
resp = requests.post(
f"{BASE}/v1/images/generations",
headers=HEADERS,
json=payload,
timeout=timeout,
)
resp.raise_for_status()
return resp.json()
Einige bewusste Entscheidungen:
- Eine Funktion, zwei Modi. Der
image-Parameter schaltet das Verhalten um, ohne dass Aufrufer verzweigen müssen. - Explizites Timeout. Das Standardverhalten von
requests– unendlich warten – ist genau die Art, einen Worker-Pool zu lahmzulegen. raise_for_status(). Lässt Fehler der HTTP-Schicht als Exceptions auftauchen, die du an einer Stelle abfangen kannst.
Polling-Hilfsfunktion hinzufügen
Wenn die Antwort eine Aufgabenkennung statt eines fertigen Bildes trägt, warte darauf:
def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
deadline = time.monotonic() + timeout
delay = initial
while time.monotonic() < deadline:
r = requests.get(
f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
)
r.raise_for_status()
data = r.json()
if data.get("status") in ("succeeded", "failed"):
return data
time.sleep(delay)
delay = min(delay * factor, cap)
raise TimeoutError(f"job {job_id} did not finish in {timeout}s")
Passe den Namen des Statusfelds an die dokumentierte Antwortstruktur an. Die Struktur selbst – begrenztes Backoff, harte Frist, Endzustandsprüfung – ist das Wesentliche und gilt unverändert, wenn du das Modell wechselst.
Zusammensetzen
if __name__ == "__main__":
result = generate(
"Eine minimalistische Studioaufnahme einer Keramiktasse, weiches Seitenlicht"
)
if "id" in result and not result.get("output"):
result = wait_for(result["id"])
print(result)
Als Nächstes umhüllst du generate mit deiner eigenen Retry- und Logging-Schicht, und die Integration hat Produktionsform.
Kostenkontrolle und häufige Fehler
Ausgaben vorhersehbar halten
Bildgenerierung wird pro Anfrage abgerechnet, der genaue Betrag hängt von Modell und Einstellungen ab – sieh im Live-Preisbereich der Konsole nach, statt Annahmen hart zu kodieren. Technische Disziplin schützt das Budget:
- Setze Limits pro Nutzer und pro Aufgabe in deinem eigenen Code. Die Plattform setzt kontoweite Grenzen; deine Anwendung sollte produktbezogene Grenzen setzen, damit ein einzelner außer Kontrolle geratener Client nicht das Konto leerräumt.
- Caching aggressiv betreiben. Hashe den normalisierten Prompt plus Einstellungen und verwende gespeicherte Ausgaben wieder. In Editor- und Vorschau-Szenarien sind identische Anfragen häufig.
- In der Auslieferungsauflösung generieren. Rendere die Größe, die du zeigen wirst; vermeide das teure Muster „groß rendern, dann verkleinern“.
- Neugenerierung nur auf ausdrückliche Nutzeraktion. Automatisches Neugenerieren bei jedem Tastenanschlag im Prompt-Feld ist der häufigste versehentliche Kostenmultiplikator.
- Protokolliere Modell, Einstellungen und Latenz bei jedem Aufruf. Ohne diese Daten kannst du nicht erkennen, welche Funktion teuer ist.
- Validiere Eingaben vor dem Absenden. Lehne leere oder außergewöhnlich lange Prompts im Client ab, damit du nie für Requests bezahlst, die zwangsläufig scheitern.
Fehler beheben, die dir tatsächlich begegnen
Gehe diese Checkliste der Reihe nach durch; sie löst die meisten Vorfälle.
- 401 / 403 – Authentifizierung. Ist der Schlüssel in der Umgebung geladen, in der die Anfrage tatsächlich läuft? Ein Schlüssel, der in deiner Shell funktioniert, existiert im Container möglicherweise nicht. Prüfe, ob das
Bearer-Präfix und der Header-Name exakt stimmen. - 404 – falscher Pfad oder falsches Modell. Versionierte Pfade und Modellkennungen ändern sich. Vergleiche Zeichen für Zeichen mit dem dokumentierten Endpunkt.
- 422 / 400 – Payload abgelehnt. Der Fehler-Body nennt das problematische Feld. Häufige Verdächtige: falsche Typen, fehlender
promptoder nicht unterstützte Parameter. Entferne optionale Einstellungen und sende erneut, um das Problem zu isolieren. - 429 – Rate Limit ausgelöst. Mit Jitter zurückweichen und erneut versuchen; nicht sofort in einer Schleife wiederholen. Unterscheide dies von einer erschöpften kontoweiten Quote, bei der Retries nichts nutzen.
- Timeouts. Wenn eine Anfrage zu lange dauert, blockierst du, wo du pollen solltest. Wechsle zum asynchronen Ablauf und setze Client-Timeouts bewusst.
- Aufgabe hängt im Zustand pending. Mit Deadline pollen und Timeout als alarmwürdigen Fehler behandeln, nicht als unendliches Warten.
Eine Gewohnheit verbindet die ganze Checkliste: Protokolliere den vollständigen Fehler-Body, nicht nur den Statuscode. Der Fehler-Body sagt dir in der Regel genau, welches Feld oder Limit das Problem ist – und verwandelt eine halbe Stunde Fehlersuche in eine Einzeiler-Korrektur.
Bringe zuerst den curl-Aufruf zum Laufen, portiere ihn in den obigen Client, bündele Polling und Fehlerbehandlung an einer Stelle – der Rest der Integration ist gewöhnlicher Anwendungscode. Zu den aktuellen Modellfähigkeiten und Preisen siehe die flux-3-Dokumentation und den Preisbereich in der HiAPI-Konsole.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen