Tutorial
So rufen Sie flux-2/text-to-image über die HiAPI-API auf: curl- und Python-Tutorial
Eine praktische Übung zu funktionierenden Anfragen: Modellbezeichner, Prompt- und Seitenverhältnis-Parameter, Antwortfelder und Fehlerbehandlung
Auf dieser Seite
Was flux-2/text-to-image über die API bereitstellt
Bevor Sie die erste Codezeile schreiben, ist es hilfreich zu verstehen, woran Sie sich eigentlich anbinden. Auf HiAPI ist flux-2/text-to-image kein separates SDK, das Sie installieren müssen, und kein neuer Dienst mit eigener Authentifizierung. Es ist ein Modellbezeichner, den Sie zusammen mit dem Prompt, der das gewünschte Bild beschreibt, an einen gemeinsamen Bildgenerierungs-Endpunkt übergeben.
Dieses mentale Modell ist wichtig, weil es die Grenzen der Integration definiert. Ihr Code benötigt drei Dinge:
- Anmeldedaten für die HiAPI-API.
- einen Endpunkt, der Bildgenerierungsanfragen akzeptiert.
- eine JSON-Nutzlast mit
model(aufflux-2/text-to-imagegesetzt) undprompt.
Alles andere – Seitenverhältnis, Ausgabevorgaben und alle weiteren vom Modell bereitgestellten Einstellungen – sind zusätzliche Felder in dieser Nutzlast. Deshalb erfordert der Wechsel von einem anderen Text-zu-Bild-Modell zu flux-2/text-to-image in der Regel nur eine Zeile Konfiguration statt eines Code-Umbaus: Der Anfrage-Umschlag bleibt gleich, nur der Wert von model ändert sich.
Der Endpunkt nimmt Ihre Anfrage entgegen, führt sie durch das Modell aus und gibt eine strukturierte Antwort zurück, die das generierte Bild (üblicherweise eine URL oder eine kodierte Nutzlast) sowie Job-Metadaten enthält. Bei einem einfachen Aufruf müssen Sie keine separate Job-Warteschlange abfragen – aus Client-Sicht ist der Request/Response-Zyklus synchron, aber die eigentliche Generierung dauert trotzdem Zeit, daher sollte der Timeout Ihres HTTP-Clients großzügig bemessen sein.
Behalten Sie dieses Bild im Kopf: ein Endpunkt, eine Nutzlast, ein Modell-String. Der Rest dieses Tutorials füllt die Nutzlast aus und härtet den Aufruf ab.
Eine funktionierende Anfrage mit curl erstellen
Der schnellste Weg zu prüfen, ob Anmeldedaten und Nutzlast korrekt sind, ist ein curl-Aufruf. Holen Sie sich zuerst eine erfolgreiche Antwort im Terminal, bevor Sie Python anfassen – so trennen Sie Authentifizierungs- und Nutzlastprobleme von Fehlern auf Sprachebene.
Legen Sie den Schlüssel zunächst als Umgebungsvariable ab, damit er nicht im Klartext in der Shell-Historie verbleibt:
export HIAPI_API_KEY="your_api_key_here"
Senden Sie dann die Anfrage:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/text-to-image",
"prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
"aspect_ratio": "16:9"
}'
Punkte, die Sie bei der Ausführung prüfen sollten:
- Endpunkt und Schlüssel stammen aus dem Dashboard Ihres HiAPI-Kontos. Den Endpunkt aus dem Dashboard zu kopieren statt ihn neu einzutippen vermeidet den häufigsten stillen Fehler – die Anfrage geht an eine unerwartete Stelle.
-sShält die Ausgabe sauber, legt aber curl-Ebene-Fehler wie DNS- oder TLS-Fehler weiterhin offen.- Der
Authorization-Header verwendet das Standard-Bearer-Schema. Keine Leerzeichen am Ende und keine Anführungszeichen um die Variablenexpansion. Content-Type: application/jsonist erforderlich; ohne ihn kann der Body abgelehnt werden, bevor das Modell ihn überhaupt sieht.
Bei erfolgreichem Aufruf sehen Sie den JSON-Antwort-Body im Terminal. Leiten Sie ihn durch einen Formatierer für bessere Lesbarkeit:
curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
| python3 -m json.tool
Sobald das funktioniert, haben Sie eine bekannt gute Basislinie. Jeder spätere Fehler in Python lässt sich mit diesem als funktionierend bestätigten Aufruf vergleichen.
Prompt- und Seitenverhältnis-Parameter
Zwei Anfragefelder haben den größten Einfluss auf die Ausgabe: prompt und aspect_ratio. Ändern Sie jeweils nur eines, sonst können Sie nicht erkennen, welches die von Ihnen beobachtete Veränderung verursacht hat.
Prompt
Der Prompt ist die natürlichsprachliche Beschreibung des Bildes. Schreiben Sie ihn als kompakte Szenenbeschreibung, nicht als Stichwortliste – grob in der Reihenfolge Subjekt, Szene, Beleuchtung und Komposition. Vergleichen Sie:
- Vage:
a lighthouse - Konkret:
a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot
Halten Sie die Formulierung beim Experimentieren eindeutig und stabil. Wenn Sie im selben Iterationsschritt Prompt und Seitenverhältnis umschreiben, haben Sie zwei Variablen und eine Beobachtung. Frieren Sie den Prompt ein, ändern Sie jeweils ein Wort und protokollieren Sie die tatsächliche Veränderung.
Praktische Gewohnheiten:
- Setzen Sie das wichtigste Subjekt an den Anfang des Strings.
- Beschreiben Sie Beleuchtung und Atmosphäre mit konkreten statt abstrakten Worten.
- Halten Sie in Ihrer Codebasis eine kleine Sammlung von Referenz-Prompts bereit und führen Sie diese erneut aus, wenn Sie etwas anderes ändern – so können Sie Modellverhaltensänderungen von Prompt-Änderungen unterscheiden.
Seitenverhältnis
aspect_ratio steuert die Form der Ausgabe – breit für Landschaften und Banner, quadratisch für Avatare und Vorschaubilder, hochkant für Poster und Mobile-Layouts. Das Modell akzeptiert Verhältnis-Strings wie 16:9, 1:1 oder hochkant-Äquivalente; verwenden Sie die in der Modelldokumentation dokumentierten Verhältnisse und erfinden Sie keine eigenen.
Da das Seitenverhältnis ein einzelnes diskretes Feld ist, ist es der am einfachsten zu variierende Parameter. Schreiben Sie eine Schleife, lassen Sie den Prompt unverändert, fordern Sie dasselbe Bild in drei Verhältnissen an und vergleichen Sie die Komposition Seite an Seite. Sie werden schnell verstehen, welche Verhältnisse das Subjekt beschneiden und welche ihm Raum lassen.
Eine Einschränkung: Das Seitenverhältnis verändert die effektive Komposition, nicht nur die Leinwand. Ein für eine breite Einstellung geschriebener Prompt kann in einem quadratischen Rahmen dünn wirken. Überprüfen Sie den Prompt nach der Festlegung des Verhältnisses einmal erneut, um das auszugleichen.
Den Aufruf nach Python portieren
Der curl-Aufruf lässt sich direkt nach Python übertragen. Ziel ist eine kleine Funktion, die einen Prompt und ein Seitenverhältnis entgegennimmt, den Schlüssel aus der Umgebung liest und das geparste JSON zurückgibt – produktionsreif statt Wegwerf-Skript.
import os
import requests
IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fail fast if unset
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
IMAGE_ENDPOINT,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
Anmerkungen, warum es so geschrieben ist:
- Umgebungsvariablen statt Literale.
os.environ[...]wirft sofort einenKeyError, wenn die Variable fehlt – weit besser, als ein leeres Bearer-Token zu senden und später einen verwirrenden Authentifizierungsfehler zu entschlüsseln. json=payloadlässtrequestsden Body für Sie serialisieren undContent-Typesetzen. Bauen Sie keinen JSON-String manuell.- Expliziter Timeout. Bildgenerierung ist nicht sofort; der Standard-Client-Timeout bringt Ihnen unter Last Ärger. Setzen Sie ihn bewusst.
raise_for_status()wandelt Nicht-2xx-Antworten in abfangbare und klassifizierbare Exceptions um, statt still einen Fehler-Body zurückzugeben, der wie Daten aussieht.
Aufrufen:
result = generate_image(
"a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
aspect_ratio="16:9",
)
print(result)
Wenn Sie httpx bevorzugen, ist die Form identisch – Import austauschen und dieselben Header, json=-Nutzlast und Timeout-Parameter beibehalten. Entscheidend ist die Nutzlast, und die bleibt gegenüber der curl-Version unverändert.
Die Antwort lesen
Ein erfolgreicher Aufruf gibt ein JSON-Objekt zurück. Statt Feldnamen zu raten, inspizieren Sie zuerst eine echte Antwort und schreiben Sie den Parser basierend auf dem, was Sie tatsächlich sehen. Führen Sie Ihre Funktion aus und geben Sie die Top-Level-Schlüssel aus:
result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())
Die Felder, die Sie üblicherweise verwenden werden, fallen in zwei Gruppen:
- Das Bild selbst. Die Antwort enthält das generierte Bild – üblicherweise eine URL, die Sie herunterladen oder bereitstellen können, manchmal kodierte Bilddaten. Lesen Sie den genauen Feldnamen aus Ihrer eigenen Antwort, speichern Sie den Wert und behandeln Sie ihn entsprechend seiner Form. Wenn es eine URL ist, behandeln Sie sie als kurzlebig: Laden Sie sie rechtzeitig herunter oder kopieren Sie sie in Ihren eigenen Speicher, statt den Link in einer Datenbank zu speichern und anzunehmen, er sei nächsten Monat noch auflösbar.
- Metadaten. Erwarten Sie begleitende Felder, die die Generierung beschreiben – das verwendete Modell, das angeforderte Seitenverhältnis oder die Größe sowie eine Kennung der Anfrage. Protokollieren Sie diese zusammen mit dem Bild. Wenn ein Nutzer meldet, das Bild „sehe falsch aus", sagt Ihnen die Metadaten, welcher Prompt und welches Verhältnis es erzeugt haben, ohne dass Sie es aus dem Anwendungszustand rekonstruieren müssen.
Ein sicheres Extraktionsmuster:
image_ref = result.get("image") or result.get("data")
if not image_ref:
raise ValueError(f"no image in response; keys={list(result.keys())}")
Das ist bewusst defensiv. Feldnamen sind innerhalb eines Modells stabil, aber den Accessor so zu schreiben, dass er mit der tatsächlichen Schlüsselliste laut fehlschlägt, verhindert, dass ein stilles None in Ihre UI propagiert. Sobald Sie die Feldnamen aus einer echten Antwort bestätigt haben, können Sie den Code straffen und sie direkt lesen.
Verwerfen Sie schließlich nicht die Rohantwort. Speichern Sie sie (oder protokollieren Sie sie für einige Anfragen), bis Ihre Integration stabil ist – sie ist die Faktenbasis, wenn stromabwärts etwas Ungewöhnliches auftritt.
Häufige Fehler und ihre Behebung
Die meisten Fehler beim ersten Lauf fallen in wenige Kategorien. Behandeln Sie sie nach HTTP-Statusklasse statt per String-Matching auf den Nachrichtentext, der sich unbemerkt ändern kann.
Authentifizierungsfehler (401 / 403)
Schlüssel fehlt, ist fehlerhaft formatiert oder hat keine Zugriffsberechtigung. Prüfen Sie der Reihe nach: Ist HIAPI_API_KEY tatsächlich in der Umgebung gesetzt, die Ihr Prozess sieht; ist der Header exakt Authorization: Bearer <key> ohne zusätzliche Leerzeichen oder umschließende Anführungszeichen; haben Sie versehentlich einen Schlüssel aus einer anderen Umgebung gesendet. Wenn curl funktioniert, Python aber nicht, geben Sie den gesendeten Header aus und vergleichen Sie Zeichen für Zeichen.
Fehlerhafte Nutzlast (400)
Der Body wird vor der Generierung abgelehnt. Häufige Ursachen: ungültiges JSON (manuell gebaute Strings mit abschließendem Komma), fehlender prompt oder falscher Content-Type. Die Lösung ist, in Python json=payload und in curl -d mit gültigem JSON zu verwenden. Geben Sie die Nutzlast, die Sie senden wollen, im Log aus und lesen Sie sie wie ein Mensch.
Nicht unterstützte oder ungültige Parameter (400 / 422)
Feldnamen oder Werte, die das Modell nicht akzeptiert – ein falsch geschriebenes aspect_ratio, ein nicht dokumentiertes Verhältnis oder ein zusätzliches Feld, das aus einem anderen Modellbeispiel kopiert wurde. Reduzieren Sie die Nutzlast auf das Minimum (model, prompt) und fügen Sie dann Feld für Feld hinzu, um das Problem zu finden.
Ratenbegrenzung (429)
Sie senden Anfragen schneller, als das Kontolimit erlaubt. Das ist vorübergehend. Wiederholen Sie nicht in einer engen Schleife – verwenden Sie Backoff mit steigender Verzögerung und einer Obergrenze für Versuche. Wenn Sie im Batch arbeiten, fügen Sie kleine Pausen zwischen den Aufrufen ein, statt alle auf einmal zu senden.
Serverseitige Fehler (5xx) und Timeouts
Diese sind vorübergehend und außerhalb Ihrer Kontrolle. Wiederholen Sie mit Backoff und stellen Sie sicher, dass der Timeout lang genug ist, damit eine langsame Generierung nicht fälschlich als Fehler eingestuft wird. Ein Read-Timeout, das ausgelöst wird, während das Modell noch arbeitet, erzeugt einen erneuten Versuch und verschwendet eine Anfrage.
Die Klassifizierung an einer Stelle zu halten, wahrt die Wartbarkeit:
def classify(status: int) -> str:
if status in (401, 403):
return "auth" # fix config, do not retry
if status in (400, 422):
return "payload" # fix request, do not retry
if status == 429:
return "rate_limit" # retry with backoff
if status >= 500:
return "server" # retry with backoff
return "other"
Den Aufruf für die Produktion kapseln
Die obige Funktion funktioniert, aber eine echte Integration braucht drei Dinge, die sie noch nicht hat: Wiederholungen, die vorübergehende von dauerhaften Fehlern unterscheiden, Timeouts, die die Realität widerspiegeln, und Logs, mit denen Sie rekonstruieren können, was passiert ist. Ein kleiner Wrapper deckt alle drei ab.
import logging
import time
log = logging.getLogger(__name__)
def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
delay = 1.0
for attempt in range(1, attempts + 1):
try:
return generate_image(prompt, aspect_ratio)
except requests.HTTPError as exc:
status = exc.response.status_code
kind = classify(status)
log.warning("flux-2 call failed", extra={
"attempt": attempt, "status": status,
"kind": kind, "aspect_ratio": aspect_ratio,
})
if kind in ("auth", "payload"):
raise # retrying will not help
if attempt == attempts:
raise
time.sleep(delay)
delay *= 2
Warum jeder Teil seinen Wert hat:
- Nur Wiederholbares wiederholen. Authentifizierungs- und Nutzlastfehler sind deterministisch – sie zu wiederholen kostet Zeit und verschleiert echte Bugs. Ratenbegrenzung, Serverfehler und Timeouts erhalten exponentielles Backoff.
- Strukturierte Felder protokollieren, keine Prosa. Versuchszahl, Status, Fehlerkategorie und verwendete Parameter ermöglichen es Ihnen später, Fehler zu gruppieren. Protokollieren Sie niemals API-Schlüssel.
- Versuche begrenzen. Eine unbegrenzte Wiederholungsschleife verwandelt einen Ausfall in einen hängenden Worker-Prozess.
- Timeouts explizit und großzügig halten. Übergeben Sie sie aus der Konfiguration, damit Sie sie in bekannten langsamen Zeiten erhöhen können, ohne Code zu ändern.
Zwei weitere Gewohnheiten, die sich auszahlen: Persistieren Sie für jedes generierte Bild einen Hash von (model, prompt, aspect_ratio), damit Sie jede Ausgabe reproduzieren können; halten Sie eine kleine Sammlung von Referenz-Prompts in Ihrer Testsuite und führen Sie diese nach jeder Änderung am Wrapper aus. Zusammen verwandeln beide das Tutorial-Snippet in etwas Betriebstaugliches.
Wenn die Anfrageform feststeht und die Fehlerbehandlung sitzt, erfordert ein späterer Modellwechsel nur eine einzeilige Änderung am Feld model – genau das ist der Sinn des Aufrufs von flux-2/text-to-image über eine einheitliche Schnittstelle.
Ä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