Tutorial
So rufen Sie qwen-image-3.0-pro/image-to-image über die HiAPI API auf: curl, Python und eine funktionierende Anfrage
Eine Integrationsübung zu asynchronen Task-Mustern, curl- und Python-Clients sowie Fehlerbehandlung
Auf dieser Seite
Warum die Bildgenerierung (image-to-image) ein asynchroner Task ist
Wenn Sie ein Bildgenerierungsmodell aufrufen, fordern Sie nicht eine String-Vervollständigung an, die innerhalb weniger hundert Millisekunden gestreamt zurückkommt. Das Modell muss Ihr Quellbild laden, den vollständigen diffusiven Generierungsprozess bedingt darauf ausführen und die Ausgabe kodieren. Das kann je nach Auflösung und Einstellungen von einigen Sekunden bis zu mehreren zehn Sekunden dauern. Eine HTTP-Verbindung über das gesamte Zeitfenster offen zu halten, ist für alle Beteiligten unrentabel: Proxys laufen in Timeouts, Load Balancer verwerfen Leerlauf-Sockets, und Ihr eigener Arbeits-Thread bleibt an eine Anfrage gebunden, die möglicherweise später noch fehlschlägt.
Deshalb verwendet der Endpunkt das Modell „erst einreichen, dann pollen“. Ihre erste Anfrage reicht einen Task ein und gibt sofort ein Task-Handle zurück. Die Bildgenerierung läuft hinter diesem Handle. Anschließend senden Sie separate, kostengünstige Anfragen, um den Task-Status zu prüfen, bis er den Abschluss meldet – dann enthält die Antwort das von Ihnen angeforderte Ergebnis.
Das hat einige praktische Konsequenzen, die Sie von Anfang an in Ihr Design einbeziehen sollten:
- Einreichen ist nicht gleich Abschluss. Eine erfolgreiche Einreichung bedeutet nur, dass die Plattform Ihren Task angenommen hat – mehr nicht. Unterscheiden Sie diese beiden Zustände in Ihrem Code.
- Die Task-ID ist Ihr einziges Handle. Speichern Sie sie persistent. Wenn Ihr Prozess zwischen Einreichen und Pollen abstürzt, ist die Task-ID Ihre Grundlage, um ohne erneute Einreichung (und erneute Bezahlung) derselben Arbeit wieder aufzusetzen.
- Pollen ist günstig, aber nicht kostenlos. Statusprüfungen sind leichtgewichtig, aber eine enge Schleife erzeugt trotzdem Traffic und kann Rate-Limits auslösen. Halten Sie Abstände ein.
- Fehler treten asynchron auf. Beschädigte Bilder oder abgelehnte Parameter können als Task-Level-Fehler erscheinen statt als HTTP-Fehler beim Einreichen. Ihr Polling-Code muss den Task-Status lesen, nicht nur den Statuscode.
Mit diesem Modell im Kopf wird die folgende Integration unkompliziert: ein Aufruf erzeugt die Arbeit, eine Schleife wartet darauf, und drei mögliche Fehlerfälle werden bewusst behandelt.
Vor dem Schreiben von Code: Was Sie vorbereiten müssen
Bevor Sie das Terminal öffnen, sammeln Sie einige Dinge, auf denen jeder Aufruf in diesem Leitfaden basiert.
HiAPI-Anmeldedaten
Sie benötigen einen API-Schlüssel für HiAPI. Behandeln Sie ihn als Geheimnis: Laden Sie ihn aus einer Umgebungsvariable, statt ihn in ein Skript einzufügen, das Sie möglicherweise committen. Die Beispiele unten lesen ihn als HIAPI_API_KEY. Die Basis-URL der API und der exakte Modellbezeichner qwen-image-3.0-pro/image-to-image sind die beiden Konstanten, auf die Sie durchgehend verweisen.
Ein Quellbild
Bildgenerierung braucht eine Eingabe. Halten Sie eine bereit und entscheiden Sie, wie Sie sie bereitstellen:
- als öffentlich zugängliche URL oder
- als hochgeladenes Asset oder kodierte Payload, je nachdem, welche Form der Endpunkt akzeptiert.
Prüfen Sie vor dem Schreiben des Aufrufs das Request-Schema des Modells, um die exakten Feldnamen und akzeptierten Quellbildformate zu bestätigen. Ein Quellbild zu liefern, das der Endpunkt nicht akzeptiert, ist die häufigste Ursache für abgelehnte Tasks, und es ist viel einfacher, dies im Voraus auszuschließen, als es anhand von Fehlermeldungen zu debuggen.
Ein Client, der pollen kann
Da der Aufruf asynchron ist, muss Ihr Werkzeug zum Senden von Anfragen auch wiederholt Folgeanfragen senden können. curl eignet sich für einen ersten Smoke-Test; jede längerfristige Nutzung sollte ein Skript sein. Es gibt keine Callback-URL zu konfigurieren und keinen Webhook zu hosten – Polling ist der Mechanismus, planen Sie also eine Schleife ein.
Ein Ort, an dem Sie Ergebnisse ansehen
Entscheiden Sie im Voraus, wie „fertig“ für Sie aussieht: eine URL, die Sie im Browser öffnen können, oder Bytes, die Sie auf die Festplatte schreiben. Das vorher zu wissen, macht auf einen Blick erkennbar, wann die Integration tatsächlich funktioniert.
Mit diesen vier Dingen zur Hand ist die erste Anfrage kurz.
Eine funktionierende Anfrage mit curl senden
Der schnellste Weg zu bestätigen, dass Ihr Schlüssel, Ihr Endpunkt und der Task-Lebenszyklus funktionieren, ist eine zweistufige curl-Sitzung. Zuerst einreichen; dann pollen.
Schritt 1: Task einreichen
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
Punkt für Punkt:
-X POST– Einreichen ist eine Erstellungsoperation.- Der
Authorization-Header trägt Ihren Schlüssel. Indem Sie eine Umgebungsvariable exportieren, statt ihn inline einzugeben, vermeiden Sie, dass er in der Shell-Historie verbleibt. Content-Type: application/json– der Request-Body ist JSON.-d– die JSON-Payload. Das Feldimageverweist auf Ihr Quellbild,promptbeschreibt die auszuführende Transformation. Die Parameternamen und akzeptierten Optionen stammen aus dem Request-Schema des Modells; prüfen Sie dort, statt zu raten.
Die Antwort auf eine erfolgreiche Einreichung ist ein Task-Objekt. Es enthält einen Bezeichner – nennen wir ihn Task-ID – sowie ein Statusfeld, das anzeigen sollte, dass der Task in der Warteschlange steht oder läuft. Notieren Sie die Task-ID; alles Weitere hängt von ihr ab.
Schritt 2: Den Task pollen
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Lesen Sie bei jedem Aufruf das Statusfeld. Wenn es den Status „ausstehend“ oder „läuft“ meldet, warten Sie einige Sekunden und prüfen Sie erneut. Wenn es Erfolg meldet, enthält die Antwort das generierte Bild – üblicherweise eine abrufbare URL oder kodierte Daten. Wenn es einen Fehler meldet, enthält die Antwort eine Fehlerbeschreibung, die den Grund erklärt.
Das ist der gesamte Lebenszyklus: eine Einreichung, dann Statusprüfungen bis zum Endzustand. Alles, was Sie danach bauen, ist nur eine bequemere Version dieser beiden Befehle, ergänzt um Warten und Fehlerbehandlung.
Denselben Aufruf in Python implementieren
Diese beiden curl-Schritte manuell zu wiederholen, wird schnell lästig, und das Kopieren der Polling-Schleife in jedes Skript ist genau der Weg, auf dem sich subtile Bugs verbreiten. Verpacken Sie das Muster aus Einreichen und Pollen in eine wiederverwendbare Funktion.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
Einige bewusste Entscheidungen sind es wert, hervorgehoben zu werden:
- Einreichen und Warten sind getrennt. Wenn die Einreichung fehlschlägt, wissen Sie das, bevor irgendein Polling stattfindet. Wenn Sie später in einem Prozess einreichen und in einem anderen einsammeln möchten, ist die Nahtstelle bereits vorhanden.
- Jede Anfrage hat ein
timeout. Anfragen ohne Timeout können unbegrenzt hängen bleiben – genau das Fehlermuster, das eine asynchrone API eigentlich für Sie vermeiden soll. - Die Polling-Schleife hat sowohl ein Intervall als auch eine Gesamtfrist. Ohne Frist würde ein Task, der im laufenden Zustand hängt, ewig schleifen. Ohne Intervall würden Sie den Endpunkt hämmern.
- Status-Strings werden explizit abgeglichen. Jeder Status, der weder Erfolg noch Fehler ist, fällt in die nächste Iteration – das ist das korrekte Standardverhalten für Zwischenzustände.
Rufen Sie sie wie jede andere Funktion auf: generate(source_url, "make the background a dusk cityscape"). Das zurückgegebene Objekt ist die finale Task-Payload, aus der Sie die Bildreferenz extrahieren.
Fehler und fehlgeschlagene Tasks behandeln
Fehler in asynchronen Workflows fallen in drei Kategorien, und jede erfordert eine andere Reaktion.
Ablehnung auf Anfrageebene
Das sind gewöhnliche HTTP-Fehlerantworten des Einreichungsaufrufs – falsche oder fehlende Anmeldedaten, fehlerhaftes JSON, nicht unterstützte Parameter, nicht erreichbares Quellbild. Sie treten auf, bevor überhaupt ein Task existiert.
Die richtige Reaktion ist fast immer: anhalten und die Meldung anzeigen. Eine fehlerhafte Payload erneut zu versuchen, verschwendet nur Kontingent und Zeit. Protokollieren Sie Statuscode und Antwortbody wörtlich; Validierungsmeldungen weisen normalerweise auf das problematische Feld hin. Zwei Fälle verdienen besondere Behandlung: Authentifizierungsfehler sollten schnell und laut fehlschlagen, weil sie auf ein Konfigurationsproblem hindeuten; Rate-Limit-Antworten können nach einem Backoff erneut versucht werden.
Aufgabenebene fehlgeschlagen
Hier war die Einreichung erfolgreich, die Task-ID existiert, aber die Arbeit ist fehlgeschlagen. Die Polling-Antwort meldet einen Fehlerstatus mit einer Fehlermeldung.
Diese Kategorie umfasst Probleme des Modells selbst: Das Quellbild lässt sich dekodieren, ist aber nicht verwendbar, der Prompt wird abgelehnt, die Generierung erreicht ein internes Limit. Da diese eng mit der Eingabe zusammenhängen, reproduziert ein blindes Wiederholen normalerweise denselben Fehler. Entscheiden Sie von Fall zu Fall: Ein vorübergehender interner Fehler kann einen erneuten Versuch wert sein; ein abgelehntes Quellbild niemals. Protokollieren Sie die Task-ID zusammen mit dem Fehler, um sie später mit einer Support-Anfrage zu korrelieren.
Endloses Polling
Die Einreichung war erfolgreich, der Task existiert, das Polling läuft – aber der Endzustand tritt nie ein. Das ist kein von der Plattform zurückgegebener Fehler; das ist eine Annahme in Ihrem Code, die ablaufen muss.
Sichern Sie sie mit einer Frist ab, wie im Python-Beispiel gezeigt. Wenn die Frist auslöst, beenden Sie das Polling. Geben Sie nicht stillschweigend ein halbfertiges Ergebnis zurück; werfen Sie einen Fehler oder geben Sie ein explizites Timeout-Ergebnis zurück, damit der Aufrufer entscheiden kann. Behalten Sie die Task-ID – der Task könnte nach Ablauf Ihrer Frist noch fertig werden, und Sie möchten ihn vielleicht später einsammeln, ohne ihn erneut einzureichen.
Eine praktische Faustregel für diese drei Kategorien: Betrachten Sie den Task-Status als einzige Wahrheitsquelle. Der HTTP-Statuscode sagt Ihnen, ob die Anfrage akzeptiert wurde; das Status- und Fehlerfeld des Tasks sagt Ihnen, ob die Arbeit erfolgreich war. Lesen Sie beides, und Fehler werden diagnostizierbar statt mysteriös.
In Produktionscode verpacken
Die obige Funktion ist eine funktionierende Integration, kein fertiger Service. Bevor sie echten Traffic trägt, sollten Sie vier Dinge straffen.
Überall Timeouts
Legen Sie für jeden Aufruf explizite Verbindungs- und Lese-Timeouts fest – Einreichen, Polling und jedes spätere Abrufen des Ergebnisbilds. Legen Sie dann eine Gesamtfrist für den gesamten Task-Lebenszyklus fest. Timeouts auf HTTP-Ebene schützen einzelne Anfragen; die Task-Frist schützt die gesamte Operation.
Urteilsfähige Wiederholungen
Wiederholen Sie nur, was sicher wiederholt werden kann. Rate-Limits beim Polling und vorübergehende Netzwerkfehler qualifizieren sich. Abgelehnte Payloads nicht. Bei Fehlern auf Aufgabenebene bedeutet Wiederholen, einen neuen Task einzureichen – das ist eine andere und teurere Operation als das Wiederholen einer Statusprüfung und sollte eine bewusste Entscheidung sein, am besten mit Obergrenze.
Logging mit Task-ID
Protokollieren Sie die Task-ID beim Einreichen und bei jedem anschließenden Statusübergang zusammen mit Zeitinformationen. Die Zeitspanne zwischen Einreichung und erstem Endzustand ist die Kennzahl, die Sie tatsächlich wollen, wenn sich etwas langsam anfühlt. Wenn Benutzer schlechte Ergebnisse melden, ist die Task-ID der Schlüssel, um eine Anekdote in einen nachvollziehbaren Datensatz zu verwandeln.
Polling aus dem Anfragepfad heraushalten
Wenn Ihre Funktion in einem Web-Handler läuft, hält eine synchrone Polling-Schleife die Anfrage während der gesamten Generierungszeit offen – genau das Problem, das das asynchrone Design vermeiden soll. Reichen Sie stattdessen im Handler ein, geben Sie die Task-ID an den Aufrufer zurück und führen Sie das Warten in einem Hintergrund-Worker, einer Queue oder einem geplanten Job aus. Dann pollt der Client Ihren Service, nicht das Modell.
In dieser Reihenfolge gebaut, wandelt sich die Integration von „funktioniert auf meiner Maschine“ zu etwas, auf das Sie sich verlassen können: einreichen, Handle persistent speichern, mit Grenzen warten und den Task-Status – nicht die Hoffnung – entscheiden lassen, wann Sie aufhören.
Ä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