So rufen Sie flux-1-kontext-max auf HiAPI auf: curl- und Python-Tutorial

Wie eine flux-1-kontext-max-Anfrage aussieht

Bevor Sie Code schreiben, ist es hilfreich, die Form der Interaktion zu verstehen. Ein Bildbearbeitungsaufruf an flux-1-kontext-max auf HiAPI ist keine schlichte Anfrage/Antwort, die das Bild im selben HTTP-Aufruf zurückgibt. Es ist eine zweiphasige Aufgabe:

1. Übermittlung – Sie senden per POST eine JSON-Nutzlast, die Ihr Eingabebild und die gewünschte Bearbeitung beschreibt. Die API nimmt die Aufgabe an und gibt einen Aufgabenbezeichner zurück.
2. Polling – Sie rufen mit diesem Bezeichner per GET den Aufgabenstatus ab, bis er den Abschluss meldet, und lesen dann die Ausgabe-URL aus der Antwort.

Dieses Muster wird verwendet, weil Bildbearbeitung rechenintensiv ist. Eine einzelne HTTP-Verbindung während des gesamten Renderings offen zu halten, ist fragil; ein Aufgaben-Handle ermöglicht es Ihnen, die Verbindung zu trennen, es erneut zu versuchen und später zurückzukehren.

Die Nutzlast gliedert sich konzeptionell in drei Teile:

• Modellauswahl – ein Feld, das flux-1-kontext-max als auszuführendes Modell angibt.
• Eingabe – in der Regel ein Bild (URL oder Base64-Nutzlast, je nach dokumentiertem Schema) plus eine Textanweisung, die die Bearbeitung beschreibt.
• Optionale Steuerparameter – Parameter, die das Generierungsverhalten anpassen, etwa Seitenverhältnis oder Seed, sofern in der Modelldokumentation angegeben.

Alles Übrige – Authentifizierungs-Header, Übermittlungs-Endpunkt, Status-Endpunkt – ist dieselbe Pipeline, die Sie bei jeder HiAPI-Aufgabe verwenden. Sobald Sie diesen Dreischritt verinnerlicht haben (Übermitteln → Polling → Herunterladen), sind die curl- und die Python-Version austauschbar, und Sie können zwischen beiden wechseln, ohne den Ablauf neu zu lernen.

Voraussetzungen und Authentifizierung

Bevor die erste Anfrage erfolgreich ist, müssen Sie einige Dinge vorbereiten.

Was Sie benötigen

• Ein HiAPI-Konto und einen im Dashboard erstellten API-Schlüssel.
• Die Basis-URL der HiAPI-API, wie in der Plattformdokumentation angegeben.
• Ein für die API erreichbares Quellbild – am häufigsten eine öffentliche HTTPS-URL. Wenn Ihr Bild privat ist, laden Sie es an einen für die API abrufbaren Ort hoch oder übergeben Sie es inline, sofern das Modellschema Base64-Eingaben unterstützt.
• curl für die Shell-Übung sowie Python 3 und die Bibliothek requests für die Code-Übung.

Authentifizierung

HiAPI authentifiziert Anfragen, indem Ihr API-Schlüssel im Autorisierungs-Header gesendet wird. Die Konvention ist ein Bearer-Token:

Authorization: Bearer $HIAPI_API_KEY

Und jede JSON-Anfrage sollte ihren Inhaltstyp deklarieren:

Content-Type: application/json

Schlüssel aus dem Quellcode heraushalten

Bewahren Sie den Schlüssel in einer Umgebungsvariable auf, statt ihn in Skripte einzufügen:

export HIAPI_API_KEY="your_key_here"

In Python lesen Sie ihn mit os.environ["HIAPI_API_KEY"]. In curl referenzieren Sie ihn als $HIAPI_API_KEY. Diese eine Gewohnheit verhindert die häufigste Ursache für kompromittierte Zugangsdaten – einen Schlüssel, der ins Repository eingecheckt und dann unter Druck rotiert werden muss.

Wenn eine Anfrage einen Authentifizierungsfehler zurückgibt, prüfen Sie drei Dinge der Reihe nach: Der Schlüssel existiert und ist gültig, der Header ist genau wie in der Dokumentation geschrieben, und in der Umgebungsvariable sind keine überflüssigen Leerzeichen oder Zeilenumbrüche enthalten.

Die Anfrage mit curl senden

Hier ist der Übermittlungsaufruf. Ersetzen Sie ihn durch Ihre eigene Bild-URL und Bearbeitungsanweisung.

curl -X POST "$HIAPI_BASE_URL/jobs" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "image": "https://example.com/input.jpg",
      "prompt": "Replace the sky with a dramatic sunset, keep the buildings unchanged"
    }
  }'

Was die einzelnen Teile bewirken

• -X POST – Eine Übermittlung ist eine Erstellungsoperation, daher POST.
• Der Endpunkt – Der jobs-Endpunkt nimmt neue Aufgaben an. Die Basis-URL stammt aus Ihrer Umgebung, sodass der Befehl zwischen Umgebungen portabel ist.
• Authorization – Ihr Bearer-Token, aus der Umgebungsvariable gelesen statt inline eingefügt.
• Content-Type: application/json – erforderlich; ohne ihn kann der Server den Anfragetext ablehnen oder fehlerhaft parsen.
• -d – die JSON-Nutzlast. model wählt flux-1-kontext-max, input.image verweist auf Ihr Quellbild, input.prompt beschreibt die Bearbeitung.

Die Antwort lesen

Eine erfolgreiche Übermittlung gibt einen JSON-Body zurück, der den Aufgabenbezeichner enthält – in der Regel ein Feld wie id oder job_id – sowie einen Status, der anzeigt, dass die Aufgabe in der Warteschlange steht oder verarbeitet wird. Speichern Sie diesen Bezeichner; das Polling hängt davon ab.

curl -s -X POST "$HIAPI_BASE_URL/jobs" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | python -m json.tool

Das Weiterleiten durch python -m json.tool gibt die Antwort formatiert aus, sodass die Aufgaben-ID leicht zu finden ist. Wenn Sie den Anfragetext in payload.json auslagern, bleibt der Befehl lesbar, auch wenn die Prompts länger werden.

Zu diesem Zeitpunkt haben Sie die Aufgabe übermittelt, aber noch kein Bild erhalten. Das Bild kommt erst nach dem Polling zurück.

Dieselbe Anfrage in Python

Die Python-Version trägt die gleiche Logik und bietet eine angenehmere Ergonomie für alles, was Sie langfristig behalten möchten.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "image": "https://example.com/input.jpg",
        "prompt": "Replace the sky with a dramatic sunset, keep the buildings unchanged",
    },
}

response = requests.post(
    f"{BASE_URL}/jobs",
    headers=headers,
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print("job id:", job["id"])

Warum dies den curl-Aufruf spiegelt

Der Parameter json=payload serialisiert das Dictionary und setzt den Inhaltstyp für Sie – die gesendeten Bytes sind identisch mit denen von curl. timeout=30 begrenzt die Übermittlungsanfrage, sodass hängende Verbindungen laut scheitern, statt Ihren Prozess zu blockieren. raise_for_status() verwandelt 4xx oder 5xx in eine Ausnahme, die Sie abfangen können, statt stillschweigend ein Fehlerdokument zurückzugeben.

Wichtige kleine Unterschiede

• Dictionary statt String – Sie bauen die Nutzlast als Python-Objekt, was das Berechnen von Prompts oder das Einschleusen von Variablen erleichtert.
• Ausnahmebehandlung – Umschließen Sie den Aufruf mit try/except requests.HTTPError, um den Antwort-Body zu protokollieren; Fehler-Nutzlasten erklären meist, was an der Eingabe falsch war.
• Kein Shell-Escaping nötig – Lange Prompts mit Anführungszeichen müssen nicht mehr escaped werden, was eine ganze Fehlerklasse beseitigt.

Die hier zurückgegebene Aufgaben-ID geht direkt in den unten beschriebenen Polling-Schritt über. Die Aufgabe ändert sich nicht dadurch, dass sie aus Python statt aus curl übermittelt wurde.

Asynchrone Aufgaben behandeln und Ergebnisse pollen

Die Übermittlung kehrt schnell zurück; das Rendering nicht. Sie warten, indem Sie den Status-Endpunkt mit der Aufgaben-ID pollen.

Die Polling-Schleife

import time

def wait_for_job(job_id, headers, interval=3, max_attempts=100):
    url = f"{BASE_URL}/jobs/{job_id}"
    for attempt in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded" or status == "completed":
            return data
        if status == "failed" or status == "error":
            raise RuntimeError(f"Job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job_id} did not finish in time")

Aufgabenstatus interpretieren

Erwarten Sie ein kleines Vokabular: einen Status queued/pending vor Beginn der Arbeit, einen Status processing/running während des Modell-Renderings und einen terminalen Status – Erfolg oder Fehlschlag. Manche APIs verwenden leicht abweichende Schreibweisen; prüfen Sie die tatsächlich erhaltene Antwort und ordnen Sie diese Strings zu, statt Annahmen zu treffen. Die entscheidende Regel: Eine Aufgabe gilt erst dann als abgeschlossen, wenn der Status ein terminaler Erfolgsstatus ist und eine Ausgabe-URL vorhanden ist. Ein 200 vom Status-Endpunkt bedeutet nicht, dass das Bild fertig ist.

Polling-Etikette

• Fordern Sie in Abständen an. Bei Bildaufgaben reichen einige Sekunden zwischen den Polls. Alle 100 ms zu pollen verschwendet Rate-Limits ohne Nutzen.
• Begrenzen Sie die Wartezeit. max_attempts begrenzt die Schleife, sodass eine hängende Aufgabe Ihren Code scheitern lässt, statt ewig zu blockieren.
• Backoff bei 429. Wenn Sie ein Rate-Limit auslösen, schlafen Sie länger und versuchen Sie es erneut, statt weiter zu hämmern.
• Webhooks bevorzugen, falls verfügbar. Wenn in der Plattformdokumentation ein Callback-Mechanismus dokumentiert ist, beseitigt er das Polling vollständig und ist im Maßstab freundlicher.

Für Shell-Tests funktioniert eine schnelle Schleife auf die gleiche Weise:

JOB_ID="your_job_id"
while true; do
  BODY=$(curl -s "$HIAPI_BASE_URL/jobs/$JOB_ID" -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$BODY"
  echo "$BODY" | grep -q '"succeeded"' && break
  sleep 3
done

Sobald Sie die Schleife verlassen, enthält die terminale Antwort die Ausgabereferenz. Das ist der nächste Schritt.

Ausgabe herunterladen und speichern

Die Antwort der abgeschlossenen Aufgabe verweist auf das gerenderte Bild, in der Regel eine URL (manchmal eine Liste). Rufen Sie es mit einer zweiten Anfrage ab und schreiben Sie die Bytes auf die Festplatte.

import pathlib

def download_output(job_data, path="edit.png"):
    out = job_data.get("output")
    if isinstance(out, list):
        out = out[0]
    url = out["url"] if isinstance(out, dict) else out

    r = requests.get(url, timeout=60)
    r.raise_for_status()
    pathlib.Path(path).write_bytes(r.content)
    return path

Worauf Sie achten sollten

• Form nicht hartcodieren. Das Ausgabefeld variiert je nach Modell – manchmal ein String-URL, manchmal ein Objekt mit url-Schlüssel, manchmal eine Liste. Prüfen Sie die tatsächliche Antwort und normalisieren Sie sie vor dem Download.
• Ausgabe-URLs können ablaufen. Behandeln Sie die URL als kurzlebig: Laden Sie sofort herunter oder kopieren Sie sie umgehend in Ihren eigenen Speicher. Speichern Sie die URL nicht als dauerhaften Datensatz für das Bild.
• Bytes validieren. Prüfen Sie, dass Content-Type mit image/ beginnt und die Dateigröße plausibel ist; eine als .png gespeicherte Fehlerseite ist ein stiller Fehlschlag.
• Transiente Download-Fehler erneut versuchen. Umschließen Sie das GET mit einem Retry mit kleinem Backoff – signierte URLs geben gelegentlich wegen Uhrzeitdrift 403 zurück, und Netzwerke schwanken.

Für eine schnelle manuelle Prüfung genügt curl:

curl -L -o edit.png "$OUTPUT_URL"

Das Flag -L folgt Weiterleitungen, die von CDN-gehosteten Ausgaben häufig verwendet werden. Nachdem die Datei geschrieben wurde, öffnen Sie sie und bestätigen Sie, dass die Bearbeitung tatsächlich dem Prompt entspricht – das ist Ihre End-to-End-Validierung, und in Pipelines, in denen Bilder bei Fehlschlag neu generiert werden müssen, lohnt es sich, eine visuelle Prüfung oder Hash-Prüfung zu automatisieren.

Häufige Fehlerstellen und Behebungen

Die meisten Erstintegrationen scheitern auf eine von wenigen Arten.

Authentifizierung und Header

• 401/403 – Schlüssel falsch, abgelaufen oder mit überflüssigen Leerzeichen. Exportieren Sie die Umgebungsvariable erneut und bestätigen Sie, dass die Header-Form der Dokumentation entspricht.
• Fehlender Content-Type – JSON ohne diesen Header zu senden, kann verwirrende 4xx-Fehler erzeugen. Fügen Sie ihn hinzu oder verwenden Sie in Python json=.

Eingabeprobleme

• Bild nicht erreichbar – Die API ruft Ihr Bild serverseitig ab. localhost-URLs oder Links, die Authentifizierung erfordern, schlagen fehl. Verwenden Sie eine öffentliche HTTPS-URL oder, falls unterstützt, Inline-Base64.
• Prompt ignoriert oder abgelehnt – Vage Anweisungen erzeugen vage Ergebnisse. Beschreiben Sie, was geändert und was beibehalten werden soll, wie im Sonnenuntergangs-Beispiel. Sehr lange Prompts können abgeschnitten werden.
• Nicht unterstützte Parameter – Felder zu übergeben, die das Modell nicht akzeptiert, kann Validierungsfehler verursachen. Beginnen Sie mit einer minimalen Nutzlast und fügen Sie dann dokumentierte Steuerparameter einzeln hinzu.

Fehler bei der asynchronen Verarbeitung

• Bild aus der Übermittlungsantwort lesen – Der Übermittlungsaufruf gibt ein Aufgaben-Handle zurück, keine Pixel. Pollen Sie zuerst.
• Jedes 200 als Abschluss werten – Der Status-Endpunkt gibt auch für noch laufende Aufgaben 200 zurück. Prüfen Sie das Statusfeld und ob eine Ausgabe-URL vorhanden ist.
• Zu schnell oder ewig pollen – Fügen Sie Intervalle und Obergrenzen hinzu, sonst erschöpfen Sie Rate-Limits und blockieren Ihren Worker.

Download-Probleme

• HTML als Bild speichern – Prüfen Sie stets Inhaltstyp und Größe.
• Abgelaufene Ausgabe-URL – Laden Sie sofort nach Abschluss herunter; reihen Sie die URL nicht für später ein.

Strukturelle Fehler

• Nicht übereinstimmende Aufgaben-IDs – Wenn Sie mehrere Aufgaben übermitteln, markieren Sie jede ID mit Ihrer eigenen Anfrage-ID, damit Polling-Ergebnisse nicht durcheinandergeraten.
• Keine Timeouts – Jede Anfrage sollte eines haben. Ohne es kann ein hängender Aufruf einen ganzen Batch blockieren.

Die Übung in eine wiederverwendbare Hilfsfunktion verwandeln

Die drei Schritte – Übermitteln, Polling, Herunterladen – gehören in eine Funktion, sodass Aufrufer die Orchestrierung nicht wiederholen müssen.

def edit_image(image_url, prompt, model="flux-1-kontext-max",
               headers=None, poll_interval=3, max_attempts=100):
    payload = {"model": model,
               "input": {"image": image_url, "prompt": prompt}}
    r = requests.post(f"{BASE_URL}/jobs", headers=headers,
                      json=payload, timeout=30)
    r.raise_for_status()
    job_id = r.json()["id"]

    data = wait_for_job(job_id, headers,
                        interval=poll_interval,
                        max_attempts=max_attempts)
    return download_output(data, path=f"{job_id}.png")

Was sie produktionsreif macht

• Ein einziger Einstiegspunkt. Aufrufer übergeben Bild und Prompt und erhalten einen Dateipfad oder eine Ausnahme. Die Workflow-Details bleiben verborgen.
• Explizite Fehler. Jede Anfrage wirft bei HTTP-Fehlern eine Ausnahme, der Poller wirft bei Aufgabenfehlschlag oder Timeout, sodass Ihre Warteschlange oder Ihr Aufrufer erneut versuchen kann.
• Konfigurierbare Zeitsteuerung. poll_interval und max_attempts sind Parameter, sodass Sie sie für schwerere Bearbeitungen lockern können, ohne die Logik anzufassen.
• Vorhersehbare Ausgabebenennung. Die Aufgaben-ID als Dateiname erleichtert die Zuordnung von Dateien zu Protokollen.

Wohin als Nächstes

Umschließen Sie den Aufruf mit Anwendungsbelangen: Protokollieren Sie Aufgaben-IDs und Latenz, wiederholen Sie fehlgeschlagene Übermittlungen mit Jitter und schieben Sie die heruntergeladenen Bytes direkt in den Objektspeicher statt auf die lokale Festplatte. Wenn Sie viele Bearbeitungen verarbeiten, übermitteln Sie zuerst einen Stapel von Aufgaben und pollen Sie sie dann gemeinsam – Übermittlungen sind günstig, und die Parallelität liegt im Warten, nicht im Hochladen.

Die Seite zu flux-1-kontext-max in der HiAPI-Dokumentation ist die Referenz für akzeptierte Felder und aktuelle Parameter. Halten Sie die Hilfsfunktion schlank und lassen Sie die Dokumentation das Schema bestimmen, dann deckt dieselbe Funktion sowohl explorative Skripte als auch echte Pipelines ab.