Tutorial
So verwendest du Google Virtual Try-On über die HiAPI API: ein Leitfaden für curl und Python
Auf dieser Seite
Was das Modell google-virtual-try-on erwartet
Bevor du eine Zeile Code schreibst, ist es hilfreich, den Eingabevertrag zu verstehen. Das Modell google-virtual-try-on ist eine Aufgabe zur Synthese zweier Bilder: Es nimmt ein Personen-/Modellbild und ein Kleidungsbild entgegen und erzeugt ein Bild der Person, die dieses Kleidungsstück trägt.
Das bedeutet, dass deine Vorbereitungsschritte immer dieselbe Form haben:
- Ein Personenbild, auf dem die Person deutlich sichtbar und sinnvoll im Bildausschnitt ist – Ganzkörper- oder Oberkörperaufnahmen funktionieren am besten, da das Modell die Körpergeometrie verstehen muss.
- Ein Kleidungsbild, am besten vor einem sauberen oder einfarbigen Hintergrund, das das Teil zeigt, das du auf die Person übertragen möchtest.
Beide Eingaben werden als Bild-URLs bereitgestellt, nicht als rohe Binärdaten im Anfragetext. Dadurch bleibt die Anfrage-Nutzlast klein, und deine eigene Speicherschicht (S3, GCS, CDN) bleibt die Quelle der Wahrheit. Deine Aufgabe ist es also, sicherzustellen, dass jede URL vor dem Aufruf öffentlich zugänglich ist – oder ausreichend lange gültig signiert wurde.
Einige praktische Einschränkungen, die du im Voraus einplanen solltest:
- Auflösung und Seitenverhältnis beeinflussen die Ausgabequalität. Sehr kleine Vorschaubilder oder übermäßig zugeschnittene Eingaben führen oft zu schlechteren Ergebnissen.
- Jeder Aufruf verarbeitet nur ein Kleidungsstück. Wenn deine Produktseite mehrere Farbvarianten hat, starte mehrere Aufrufe, statt zu versuchen, mehrere Teile in eine Anfrage zu packen.
- Die Paarung liegt in deiner Verantwortung. Das Modell prüft nicht, ob das Kleidungsstück „zur“ Person „passt“; es synthetisiert lediglich, was du bereitstellst. Eine gute Paarung (Ganzkörperaufnahme mit Kleid, Oberkörperaufnahme mit Jacke) führt deutlich sichtbar zu besseren Ergebnissen.
Betrachte diesen Schritt als Asset-Vertrag: Wenn du für jede Aufgabe zuverlässig zwei hochwertige URLs erzeugen kannst, besteht der Rest der Integration aus geradlinigem Pipeline-Aufbau.
Deine HiAPI-Anfrage einrichten
Alle HiAPI-Modellaufrufe folgen derselben Form. Sobald einer funktioniert, musst du bei den anderen nur die Parameter austauschen. Das Folgende ist für google-virtual-try-on erforderlich.
Endpunkt und Methode
Anfragen werden als POST an den HiAPI-Modellaufruf-Endpunkt für google-virtual-try-on gesendet. Du verwendest dieselbe Basis-URL und dieselben Anmeldedaten für alle Modelle – das ist der Hauptgrund, über HiAPI zu routen, statt jeden Anbieter einzeln anzubinden.
Authentifizierung
Authentifiziere dich im Header Authorization mit deinem HiAPI-API-Schlüssel im Standard-Bearer-Token-Format:
Authorization: Bearer $HIAPI_API_KEY
Bewahre den Schlüssel serverseitig auf. Verteile ihn niemals in Browser-Bundles oder mobilen Apps – das Proxyen über dein eigenes Backend ist sowohl sicherer als auch ein Ort, an dem du Rate-Limiting und Logging ergänzen kannst.
Content-Type
Sende den Anfragetext als JSON:
Content-Type: application/json
Anfragetext
Der Anfragetext enthält deinen Modellbezeichner sowie die beiden Bild-URLs aus dem vorherigen Abschnitt – das Personenbild und das Kleidungsbild – plus alle optionalen Parameter, die das Modell bereitstellt. Die genauen Parameternamen sind in der Dokumentation neben dem Modell dokumentiert; kopiere sie wörtlich, statt zu raten, denn ein Tippfehler im Feldnamen äußert sich meist als Validierungsfehler statt als hilfreiche Meldung.
Deine Konfiguration speichern
Lege Basis-URL, Modellbezeichner und Schlüssel in Umgebungsvariablen ab, damit dasselbe Skript ohne Änderungen in Staging und Produktion verwendet werden kann:
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
Das war die gesamte Einrichtung. Kein SDK, keine anbieterspezifische Anbindung.
Eine funktionierende curl-Anfrage
Der schnellste Weg, um zu prüfen, ob Schlüssel und Nutzlast korrekt sind, ist ein einzelner curl-Aufruf. Hier die Anatomie einer Anfrage an google-virtual-try-on:
curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google-virtual-try-on",
"input": {
"model_image": "https://your-cdn.example.com/person-001.jpg",
"garment_image": "https://your-cdn.example.com/jacket-front.jpg"
}
}'
Einige Punkte sind zu beachten:
- Beide Bildfelder liegen im
input-Objekt, wodurch modellspezifische Parameter namensräumlich getrennt und von den Routing-Feldern abgesondert bleiben. - Die URLs müssen vom Server aus erreichbar sein, nicht von deinem Laptop. Eine
localhost- oder nur per VPN erreichbare Adresse schlägt fehl. - Bei diesem Aufruf gibt es keinen Datei-Upload-Schritt. Wenn deine Assets noch nicht auf einem CDN liegen, lade sie zuerst hoch und verwende die erzeugten URLs.
Führe ihn einmal aus und prüfe das zurückgegebene rohe JSON, bevor du etwas darauf aufbaust. Die Ausgabe durch einen Formatter zu leiten, macht sie lesbarer:
curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Den Anfragetext in einer Datei request.json zu speichern, vermeidet außerdem Shell-Quoting-Fehler, wenn die Nutzlast wächst.
Dieselbe Anfrage in Python
Für alles, was über einen einmaligen Test hinausgeht, wechsle zu Python. Das folgende Beispiel verwendet nur die Standardbibliothek plus requests, sodass es direkt in ein Skript, eine Lambda-Funktion oder einen kleinen Dienst passt, ohne zusätzliches Framework.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
payload = {
"model": "google-virtual-try-on",
"input": {
"model_image": person_url,
"garment_image": garment_url,
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(
f"{BASE_URL}/v1/models/google-virtual-try-on",
json=payload,
headers=headers,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = try_on(
"https://your-cdn.example.com/person-001.jpg",
"https://your-cdn.example.com/jacket-front.jpg",
)
print(result)
Hinweise zur Anpassung:
- Setze explizite Timeouts. Die Bildgenerierung erfolgt nicht sofort; der Standard-Timeout von
requestsist für solche Aufrufe zu aggressiv. Wähle einen Wert, der bequem über deiner p99-Latenz liegt. - Verwende
json=payload, nichtdata=json.dumps(payload). Das setzt den Content-Type für dich und vermeidet Doppelkodierungs-Bugs. - Gib das geparste JSON zurück, nicht das Response-Objekt, damit Aufrufer nicht versehentlich von HTTP-Interna abhängen. Wenn du Statuscodes für Metriken benötigst, erfasse sie vor der Rückgabe.
- Trenne Client und Workflow. In einem echten Dienst gehört die obige Funktion in ein leichtgewichtiges Client-Modul; Queue, Speicherung und Wiederholungen liegen eine Ebene darüber.
Wenn du bereits httpx oder ein asynchrones Framework verwendest, ist die Umstellung mechanisch – Nutzlast und Header sind identisch.
Die Antwort lesen
Die Antwort ist JSON. Betrachte sie als einen kleinen Umschlag, der sich auf zwei Dinge konzentriert: War die Aufgabe erfolgreich, und wo ist die Ausgabe?
Im Allgemeinen solltest du prüfen:
- Transportstatus. 2xx bedeutet, dass die Anfrage akzeptiert und verarbeitet wurde. 4xx bedeutet, dass deine Anfrage fehlerhaft war; 5xx bedeutet, dass auf Serverseite etwas schiefgelaufen ist. Protokolliere den Statuscode bei jedem Aufruf – das ist die billigste Beobachtungsmöglichkeit, die du ergänzen kannst.
- Felder im Antworttext. Die Nutzlast enthält das Generierungsergebnis. Bildergebnisse werden als URL zurückgegeben, die auf das erzeugte Asset zeigt. Der genaue Feldname richtet sich nach dem Antwort-Schema des Modells; parse defensiv, statt einen einzelnen String anzunehmen.
- Metadaten. Alle Nutzungs- oder Laufzeitfelder in der Antwort sind es wert, erfasst zu werden. Die Abrechnung erfolgt über die Plattform, daher ermöglicht dir das Persistieren von Metadaten pro Anfrage, deine Logs später mit dem Dashboard abzugleichen.
Ein robustes Parsing sieht so aus:
data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
raise RuntimeError(f"No image in response: {data}")
Wie du mit dem Ergebnis umgehst
Die zurückgegebene URL ist ein generiertes Asset, kein dauerhaftes Asset. Gib sie nicht einfach an das Frontend weiter und vergiss sie. Stattdessen:
- Herunterladen und neu hosten. Hole die Bytes sofort ab und schreibe sie mit einem inhaltsadressierten Schlüssel in deinen eigenen Bucket. Das entkoppelt dein Produkt von der Aufbewahrungsrichtlinie des Generators.
- Provenienz aufzeichnen. Speichere die Eingabe-URLs, den Modellbezeichner und den Zeitstempel zusammen mit der Ausgabe. Wenn ein Händler fragt, warum ein bestimmtes Anprobierergebnis so aussieht, wirst du die exakte Aufgabe reproduzieren müssen.
- Formate normalisieren. Passe Größe und Format bei der Aufnahme einmalig an und konvertiere in das Standardformat des Store-Frontends, statt dies bei jedem Seitenaufruf zu tun.
Die Antwort als kurzlebige Übergabe zu behandeln – parsen, herunterladen, speichern, verwerfen – ist das skalierbare Muster.
Fehlermodi und Wiederholungsstrategie
Nicht jeder Fehler verdient eine Wiederholung. Blindes Wiederholen verwandelt einen kleinen Upstream-Hiccup in eine volle Queue doppelter Aufgaben und eine überraschende Rechnung.
Vor der Wiederholung klassifizieren
Nicht wiederholen – Anfrage korrigieren:
400-artige Validierungsfehler: fehlerhaftes JSON, fehlende oder falsch benannte Felder, Anfragetext entspricht nicht der erwarteten Modellstruktur.401/403: API-Schlüssel falsch oder fehlend, oder der Schlüssel hat keinen Zugriff auf das Modell. Wiederholen hilft nie.404: Modellbezeichner oder Endpunktpfad falsch.- Nicht erreichbare Bild-URLs. Wenn die Personen- oder Kleidungs-URL beim Abrufen 404 zurückgibt oder timeoutet, kann die Generierung nicht fortgesetzt werden. Validiere URLs vor dem Absenden.
Mit Backoff wiederholen:
429: Du wurdest rate-limitiert. Gehe mit Backoff zurück und respektiere das Signal.5xx: vorübergehender Dienst- oder Upstream-Fehler.- Fehler auf Netzwerkebene: Verbindungsresets, Lese-Timeouts.
Begrenzte Wiederholungen mit Jitter
Begrenze die Anzahl der Versuche – drei ist eine übliche Obergrenze – und verwende exponentielles Backoff mit zufälligem Jitter, damit eine Gruppe von Workern nicht synchron wiederholt:
import random, time
def with_retry(fn, attempts=3, base=1.0):
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status is not None and 400 <= status < 500 and status != 429:
raise # client error: do not retry
if i == attempts - 1:
raise
time.sleep(base * (2 ** i) + random.uniform(0, 0.5))
Produktionsschutzmaßnahmen
- Idempotenz auf Aufgabenebene. Hashe das Paar der Eingabe-URLs zu einem Aufgabenschlüssel. Wenn derselbe Schlüssel bereits läuft oder abgeschlossen ist, gib das gespeicherte Ergebnis zurück, statt erneut zu übermitteln.
- Dead-Letter-Queue. Wenn die Wiederholungen erschöpft sind, lege die Aufgabe mit ihrem vollständigen Kontext ab, statt sie stillschweigend zu verwerfen.
- Circuit Breaker. Wenn die Fehlerrate einen Schwellenwert überschreitet, stoppe die Übermittlung für eine Abklingzeit, statt weiter auf einen kämpfenden Dienst einzuhämmern.
- Nach Form alarmieren, nicht nur nach Anzahl. Ein Anstieg von 4xx nach einem Deployment bedeutet meist, dass jemand ein Feld umbenannt hat.
Eingaben früh validieren
Die meisten „Modellfehler“ sind tatsächlich schlechte Eingaben. Führe eine billige Vorabprüfung durch: Sende eine HEAD-Anfrage an jede URL, prüfe Content-Type und ungefähre Größe und lehne offensichtlich unbrauchbare Assets ab, bevor du einen kostenpflichtigen Aufruf ausgibst. Diese eine Gewohnheit eliminiert den Großteil deines Wiederholungsverkehrs.
In eine echte Pipeline integrieren
Ein erfolgreicher curl-Aufruf ist nur eine Demo. Eine zuverlässige Produktfunktion braucht etwas mehr Struktur drumherum.
Den Prozess in Phasen strukturieren
Eine praktikable Aufteilung:
- Aufnahme. Ein Händler oder interner Nutzer reicht ein Personenbild und ein Kleidungsbild ein. Speichere beide in deinem Objektspeicher und erzeuge stabile, signierte URLs.
- Validierung. Prüfe Erreichbarkeit, Format und Größe. Lehne früh mit klaren Hinweisen ab.
- Übermittlung. Rufe
google-virtual-try-onüber das Client-Modul auf. Zeichne Aufgabenschlüssel, Modellbezeichner und Eingabe-URLs in der Datenbank auf. - Materialisierung. Nach Erfolg lade das generierte Bild herunter, konvertiere es in dein Standardformat und schreibe es mit deterministischem Schlüssel in dein CDN.
- Veröffentlichung. Aktualisiere den Aufgaben-Datensatz so, dass er auf dein gehostetes Asset zeigt, und lass das Store-Frontend nur aus deinem eigenen Speicher lesen.
Jede Phase ist unabhängig wiederholbar – genau das macht das Gesamtsystem debugbar. Wenn Schritt 4 fehlschlägt, musst du die Generierung nicht erneut ausführen.
Den Client leichtgewichtig halten
Lege den HTTP-Aufruf in ein kleines Modul und platziere die Richtlinien (Wiederholungen, Parallelität, Timeouts, Logging) drumherum. Wenn HiAPI Parameter für ein Modell hinzufügt oder du verschiedene Bildgenerierungs-Routen per A/B-Test vergleichen willst, änderst du nur eine Datei.
Betriebliche Gewohnheiten, die sich lohnen
- Standardmäßig asynchron. Die Generierung dauert Sekunden, manchmal länger. Übermittle aus einem Worker, nicht aus dem Request-Handler, auf den ein Nutzer wartet.
- Aggressiv cachen. Dasselbe Paar aus Person und Kleidungsstück sollte niemals zweimal generiert werden. Adressiere die Ausgabe inhaltsbasiert und prüfe vor der Übermittlung.
- Mit Sichtbarkeit budgetieren. Da die Nutzung über die Plattform abgerechnet wird, protokolliere Metadaten pro Anfrage und gleiche sie regelmäßig mit deinem HiAPI-Dashboard ab. So erkennst du eine außer Kontrolle geratene Wiederholungsschleife in Stunden statt am Monatsende.
- Prompts und Parameter versionieren. Speichere das Parameterobjekt mit jeder Aufgabe, damit du Ergebnisse nach Änderungen reproduzieren kannst.
- Sichtbar für Nutzer fehlschlagen. Ein Ladeanimation, die nie verschwindet, ist schlimmer als ein ehrliches „Wir konnten das nicht generieren, bitte probiere ein anderes Foto“.
Nächste Schritte
Dieselbe Anfrageform gilt für andere HiAPI-Bildmodelle, sodass der hier gebaute Client zur Vorlage für den Rest deiner Pipeline wird. Sobald der Aufruf mit zwei Bildern stabil ist, durchstöbere den Modellkatalog, um zu sehen, was sonst zu deinem Workflow passt – Authentifizierung, Fehlerbehandlung und Speichermuster bleiben unverändert.
Ä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