API FASHN Try-On v1.6: esempi di richieste curl e Python funzionanti

FASHN Try-On v1.6 è un modello di prova virtuale (image-to-image) disponibile su hiapi. Gli fornisci due immagini — una foto di una persona e una foto di un capo d'abbigliamento — e restituisce un'immagine composita in cui il capo viene indossato. Questo articolo è una guida pratica per sviluppatori all'fashn try-on api: include una richiesta reale a /v1/tasks che ho eseguito completamente, lo schema di input completo verificato rispetto al validatore di parametri online e i dettagli di produzione che non sono documentati nella tabella dei parametri.

Pagina del modello e prova online: FASHN Try-On v1.6.

1. Cosa costruirai + prerequisiti

L'intero flusso è il classico pattern di attività asincrona: una POST crea l'attività, poi si esegue il polling fino a quando l'attività raggiunge uno stato terminale, quindi si scarica l'immagine di output.

Ti serve:

• Una chiave API (sk-...), ottenibile dalla guida rapida di hiapi.
• Due URL di immagini accessibili pubblicamente: la foto della persona per model_image e la foto del capo per garment_image.

2. Esempio minimo funzionante

Creare l'attività (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"
    }
  }'

Risposta — questa è un'attività accettata, non un'immagine finita:

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

model_image e garment_image sono gli unici campi obbligatori; tutti gli altri hanno valori predefiniti.

Eseguire il polling del risultato (curl)

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

Al termine dell'attività otterrai data.status: "success" e l'immagine si troverà in 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"
}

Il campo expireAt è importante: l'output viene conservato in archiviazione temporanea (TTL di circa 7 giorni). Scarica o copia subito questi byte — non usare hotlink diretti.

Eseguire end-to-end con Python

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. Schema di input (verificato rispetto al validatore online)

fashn-tryon-v1.6 usa uno schema chiuso — qualsiasi campo non elencato di seguito viene rifiutato, quindi non puoi includere parametri aggiuntivi nativi di FASHN che hiapi non espone.

Campo	Obbligatorio	Tipo	Valori accettati
model_image	Sì	string (URL)	Foto della persona
garment_image	Sì	string (URL)	Foto del capo d'abbigliamento
category	No	enum	tops, bottoms, one-pieces, auto
mode	No	enum	performance, balanced, quality
garment_photo_type	No	enum	auto, model, flat-lay
output_format	No	enum	png, jpeg
seed	No	integer	Per la riproducibilità
segmentation_free	No	boolean	—

Come l'ho verificato: inviando {"model":"fashn-tryon-v1.6","input":{}} si ottiene

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

Ogni valore enum sopra è stato confermato inviando un valore non valido, ad esempio mode: value must be one of 'performance', 'balanced', 'quality'. Passando num_samples, num_images o qualsiasi campo al di fuori della tabella si ottiene additional properties '...' not allowed — non esiste un'opzione multi-campione. Una richiesta restituisce un'immagine; per ottenere risultati diversi, modifica seed tra chiamate diverse.

4. Pratiche per la produzione

• La validazione avviene prima della fatturazione. Un input non valido restituisce HTTP 400 con corpo {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."} e non crea alcuna attività — le richieste malformate non generano costi. Una richiesta valida restituisce code:200 con un taskId.
• Ripeti il polling, non la sottomissione. Ogni POST /v1/tasks crea una nuova attività (fatturabile). Se una richiesta di polling va in timeout, continua a interrogare il taskId che possiedi già; una risposta persa non significa che l'attività sia fallita.
• Usa i callback invece del polling. Per scenari in batch puoi registrare un callback che consenta a hiapi di notificarti quando l'attività raggiunge lo stato finale, senza dover eseguire tu stesso il polling — vedi la documentazione di riferimento dell'API asincrona unificata per i campi specifici. Gli esempi sopra usano il polling.

5. Come si è comportata una vera esecuzione

Ho eseguito la richiesta minima sopra — una foto di una persona da 768×1152 e un'immagine di un capo da 768×1152, omettendo mode e category:

• Latenza: sull'oggetto attività, circa 13 secondi da created a completed.
• Output: un singolo PNG di 768×1152, cioè un'immagine in verticale. La pagina del modello indica che la dimensione dell'output segue la foto della persona (nelle sue esecuzioni verificate sono state misurate le dimensioni 972×1296 e 768×1152) e questa esecuzione è coerente — non esistono campi width/height/aspect_ratio, quindi è la dimensione della foto della persona a determinare quella dell'output.
• Percorso degli stati: durante il polling è apparsa prima archiving, poi success; storage era temp.
• I valori predefiniti funzionano davvero. Omettere mode e category ha comunque avuto successo, quindi i due URL delle immagini sono davvero gli unici input obbligatori — il modello identifica automaticamente il tipo di capo.

La fatturazione si basa sul numero di immagini di output e non varia con il mode scelto; per le tariffe attuali consulta la pagina dei prezzi.

Link correlati

• Pagina del modello FASHN Try-On v1.6 e prova online
• Documentazione di riferimento dell'API asincrona (task) unificata
• Guida rapida — ottenere la chiave API
• Prezzi

Domande frequenti

Quali campi sono obbligatori? Solo model_image e garment_image, ed entrambi devono essere URL accessibili pubblicamente.

Si possono generare più varianti con una sola chiamata? No — num_samples e num_images vengono rifiutati dallo schema. Una richiesta restituisce un'immagine; modifica seed tra chiamate diverse per ottenere risultati diversi.

Come si controllano le dimensioni dell'output? Non puoi impostarle direttamente. Il risultato segue le dimensioni della foto della persona — il mio input da 768×1152 ha prodotto un output da 768×1152.

Quanto dura l'URL del risultato? L'output si trova in archiviazione temporanea, con expireAt (circa 7 giorni). Scarica subito questi byte.

La modalità qualità cambia il prezzo? No — indipendentemente da performance, balanced o quality, la fatturazione si basa sul numero di immagini di output.