FASHN Try-On v1.6 API: Verfügbare curl- und Python-Anfragebeispiele

FASHN Try-On v1.6 ist ein virtuelles Anprobe-Modell (Image-to-Image) auf hiapi. Du gibst ihm zwei Bilder – ein Personenfoto und ein Kleidungsfoto – und es liefert ein zusammengesetztes Ergebnisbild zurück, das die Kleidung am Körper zeigt. Dieser Artikel ist ein praxisorientierter fashn try-on api-Leitfaden für Entwickler: Er enthält eine echte, von mir vollständig durchgeführte /v1/tasks-Anfrage, das vollständige Eingabe-Schema, das ich gegen den Online-Parameter-Validator geprüft habe, sowie Produktionsdetails, die in der Parametertabelle nicht aufgeführt sind.

Modellseite und Online-Demo: FASHN Try-On v1.6.

1. Was du baust + Voraussetzungen

Der gesamte Ablauf folgt dem standardmäßigen asynchronen Task-Muster: Ein POST erstellt die Aufgabe, dann pollst du, bis die Aufgabe einen Endzustand erreicht, und lädst anschließend das ausgegebene Bild herunter.

Du benötigst:

• Einen API key (sk-...), erhältlich über den hiapi Quickstart.
• Zwei öffentlich zugängliche Bild-URLs: ein Personenfoto für model_image und ein Kleidungsfoto für garment_image.

2. Minimales lauffähiges Beispiel

Aufgabe erstellen (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

Antwort – dies ist eine akzeptierte Aufgabe, kein fertiges Bild:

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image und garment_image sind die einzigen Pflichtfelder; alle anderen Felder haben Standardwerte.

Ergebnis pollen (curl)

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

Nach Abschluss der Aufgabe erhältst du data.status: "success", und das Bild befindet sich unter data.output[0].url:

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

Das expireAt ist hier wichtig: Die Ausgabe liegt im temporären Speicher (TTL ca. 7 Tage). Lade diese Bytes sofort herunter oder speichere sie um – verlinke sie nicht direkt per Hotlink.

End-to-End mit Python ausführen

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. Eingabe-Schema (gegen den Online-Validator verifiziert)

fashn-tryon-v1.6 verwendet ein geschlossenes Schema – jedes Feld, das unten nicht aufgeführt ist, wird abgelehnt. Du kannst also keine zusätzlichen nativen FASHN-Parameter einschmuggeln, die hiapi nicht bereitstellt.

Feld	Pflichtfeld	Typ	Zulässige Werte
model_image	Ja	string (URL)	Personenfoto
garment_image	Ja	string (URL)	Kleidungsfoto
category	Nein	enum	tops, bottoms, one-pieces, auto
mode	Nein	enum	performance, balanced, quality
garment_photo_type	Nein	enum	auto, model, flat-lay
output_format	Nein	enum	png, jpeg
seed	Nein	integer	Zur Reproduzierbarkeit
segmentation_free	Nein	boolean	—

Wie ich das bestätigt habe: Das Senden von {"model":"fashn-tryon-v1.6","input":{}} liefert

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

Jeder der obigen Enum-Werte wurde durch Senden eines ungültigen Werts bestätigt, z. B. mode: value must be one of 'performance', 'balanced', 'quality'. Die Übergabe von num_samples, num_images oder eines beliebigen Felds außerhalb der Tabelle führt zu additional properties '...' not allowed – es gibt keine Multi-Sample-Option. Eine Anfrage liefert ein Bild; für unterschiedliche Ergebnisse kannst du seed über mehrere Aufrufe hinweg variieren.

4. Praxis in der Produktion

• Die Validierung erfolgt vor der Abrechnung. Ungültige Eingaben liefern HTTP 400 mit dem Antwortkörper {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}, und es wird keine Aufgabe erstellt – fehlerhafte Anfragen verursachen keine Kosten. Gültige Anfragen liefern code:200 mit einer taskId.
• Erneut pollen statt erneut senden. Jedes POST /v1/tasks erstellt eine neue (abrechenbare) Aufgabe. Wenn eine Polling-Anfrage ein Timeout hat, pollst du weiter mit der taskId, die du bereits hast; eine verlorene Antwort bedeutet nicht, dass die Aufgabe fehlgeschlagen ist.
• Callbacks statt Polling verwenden. Für Batch-Szenarien kannst du einen Callback registrieren, damit hiapi dich benachrichtigt, sobald die Aufgabe einen Endzustand erreicht, statt selbst zu pollen – die entsprechenden Felder findest du in der Referenz zur einheitlichen asynchronen API. Das obige Beispiel verwendet Polling.

5. Wie ein echter Durchlauf verlief

Ich habe die obige minimale Anfrage ausgeführt – mit einem Personenfoto mit 768×1152 und einem Kleidungsbild mit 768×1152, wobei ich mode und category weggelassen habe:

• Latenz: Im Task-Objekt etwa 13 Sekunden von created bis completed.
• Ausgabe: Ein einzelnes PNG mit den Maßen 768×1152, also ein Hochformat-Bild. Die Modellseite gibt an, dass die Ausgabegröße dem Personenfoto folgt (in ihren verifizierten Läufen wurden 972×1296 und 768×1152 gemessen); dieser Lauf stimmt damit überein – es gibt keine width/height/aspect_ratio-Felder, daher bestimmt die Größe des Personenfotos die Ausgabegröße.
• Statusverlauf: Beim Polling erschien zunächst archiving, danach success; storage war temp.
• Die Standardwerte funktionieren tatsächlich. Das Weglassen von mode und category war trotzdem erfolgreich, die beiden Bild-URLs sind also tatsächlich die einzigen zwingend erforderlichen Eingaben – das Modell erkennt den Kleidungstyp automatisch.

Die Abrechnung erfolgt nach Anzahl der Ausgabebilder und ändert sich nicht je nach gewähltem mode; die aktuellen Tarife findest du auf der Preisseite.

Verwandte Links

• FASHN Try-On v1.6 Modellseite und Online-Demo
• Referenz zur einheitlichen asynchronen (Task-)API
• Quickstart – API key erhalten
• Preise

Häufig gestellte Fragen

Welche Felder sind Pflichtfelder? Nur model_image und garment_image, und beide müssen öffentlich zugängliche URLs sein.

Kann ein Aufruf mehrere Varianten generieren? Nein – num_samples und num_images werden vom Schema abgelehnt. Eine Anfrage liefert ein Bild; ändere seed zwischen mehreren Aufrufen, um unterschiedliche Ergebnisse zu erhalten.

Wie lässt sich die Ausgabegröße steuern? Gar nicht direkt. Das Ergebnis folgt der Größe des Personenfotos – mein Eingabebild mit 768×1152 erzeugte eine Ausgabe mit 768×1152.

Wie lange ist die Ergebnis-URL gültig? Die Ausgabe liegt im temporären Speicher und hat ein expireAt (ca. 7 Tage). Lade diese Bytes sofort herunter.

Ändert der Qualitätsmodus den Preis? Nein – unabhängig von performance, balanced oder quality wird nach Anzahl der Ausgabebilder abgerechnet.