Tutoriale
Come usare Google Virtual Try-On tramite l'API HiAPI: guida con curl e Python
In questa pagina
Cosa si aspetta il modello google-virtual-try-on
Prima di scrivere qualsiasi codice, è utile capire il contratto di input. Il modello google-virtual-try-on è un'attività di composizione a due immagini: riceve un'immagine di una persona/modella e un'immagine di un capo e genera un'immagine della persona che indossa quel capo.
Ciò significa che i tuoi passaggi di preparazione hanno sempre la stessa forma:
- Un'immagine della persona, con il soggetto chiaramente visibile e inquadrato ragionevolmente: le foto a figura intera o a mezzo busto funzionano meglio, perché il modello deve comprendere la geometria del corpo.
- Un'immagine del capo, preferibilmente su sfondo pulito o a tinta unita, che mostri il singolo articolo che vuoi trasferire sulla persona.
Entrambi gli input vengono forniti come URL di immagini, non come dati binari grezzi nel corpo della richiesta. Questo mantiene il payload leggero e lascia che il tuo livello di archiviazione (S3, GCS, CDN) resti la fonte di verità. Il tuo compito, quindi, è assicurarti che ogni URL sia pubblicamente accessibile prima di effettuare la chiamata, oppure firmato con una validità sufficientemente lunga.
Ci sono alcuni vincoli pratici da pianificare in anticipo:
- Risoluzione e proporzioni influenzano la qualità dell'output. Miniatura molto piccole o input eccessivamente ritagliati tendono a produrre risultati scadenti.
- Ogni chiamata gestisce un solo capo. Se la pagina del tuo prodotto ha più varianti di colore, effettua più chiamate invece di cercare di inserire più articoli in un'unica richiesta.
- L'abbinamento è compito tuo. Il modello non verifica se il capo sia "adatto" alla persona; compone semplicemente ciò che gli fornisci. Un buon abbinamento (figura intera con vestito, mezzo busto con giacca) produce output visibilmente migliori.
Considera questo passaggio come il contratto sugli asset: se riesci a generare in modo affidabile due URL di qualità per ogni attività, il resto dell'integrazione è un semplice lavoro di impianto.
Configurare la richiesta HiAPI
Tutte le chiamate ai modelli HiAPI seguono la stessa forma, quindi una volta che ne hai una funzionante, le altre richiedono solo la sostituzione dei parametri. Ecco cosa serve per google-virtual-try-on.
Endpoint e metodo
La richiesta viene inviata con POST all'endpoint di chiamata del modello HiAPI google-virtual-try-on. Usi lo stesso URL di base e le stesse credenziali per tutti i modelli: questo è anche il motivo principale per scegliere di passare per HiAPI invece di integrare singolarmente ogni provider.
Autenticazione
Autenticati con la tua API key HiAPI nell'header Authorization, nel formato standard bearer token:
Authorization: Bearer $HIAPI_API_KEY
Mantieni la chiave sul server. Non distribuirla mai in bundle per il browser o in app mobile: passare dal tuo backend è più sicuro e ti offre anche un punto in cui aggiungere rate limiting e logging.
Tipo di contenuto
Invia il corpo della richiesta in JSON:
Content-Type: application/json
Corpo della richiesta
Il corpo della richiesta contiene il tuo identificatore del modello e i due URL delle immagini della sezione precedente — immagine della persona e immagine del capo — più eventuali parametri opzionali esposti dal modello. I nomi esatti dei parametri sono quelli documentati accanto al modello; copiali letteralmente invece di indovinarli, perché un errore di ortografia in un nome di campo di solito si manifesta come errore di validazione, non come un messaggio utile.
Salva la tua configurazione
Metti l'URL di base, l'identificatore del modello e la chiave in variabili d'ambiente, così lo stesso script funziona senza modifiche in staging e in produzione:
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
La configurazione è tutta qui. Nessun SDK, nessuna integrazione per singolo provider.
Una richiesta curl funzionante
Il modo più rapido per verificare che chiave e payload siano corretti è una singola chiamata curl. Ecco l'anatomia di una richiesta a 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"
}
}'
Alcune cose da notare:
- I due campi immagine si trovano all'interno dell'oggetto
input, il che isola i parametri specifici del modello e li separa dai campi di routing. - Gli URL devono essere raggiungibili dal server, non dal tuo laptop. Un indirizzo
localhosto accessibile solo via VPN fallirà. - In questa chiamata non c'è alcun passaggio di caricamento file. Se i tuoi asset non sono ancora sulla CDN, caricali prima e usa gli URL generati.
Eseguila una volta e controlla il JSON grezzo restituito prima di costruirci sopra qualsiasi cosa. Passare l'output attraverso un formattatore ne facilita la lettura:
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
Salvare il corpo della richiesta in un file request.json evita anche errori di quoting della shell quando il payload cresce.
La stessa richiesta in Python
Per qualsiasi scenario che vada oltre un test occasionale, passa a Python. L'esempio seguente usa solo la libreria standard più requests, quindi può essere inserito direttamente in uno script, in una Lambda o in un piccolo servizio, senza framework aggiuntivi.
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)
Note sull'adattamento:
- Imposta timeout espliciti. La generazione di immagini non è istantanea; il timeout predefinito di
requestsè troppo aggressivo per questo tipo di chiamate. Scegli un valore comodamente superiore alla tua latenza p99. - Usa
json=payload, nondata=json.dumps(payload). Imposta il content type per te ed evita i bug di doppia codifica. - Restituisci il JSON analizzato, non l'oggetto response, così i chiamanti non dipendono accidentalmente dai dettagli interni di HTTP. Se ti servono i codici di stato per le metriche, catturali prima di restituire.
- Separa il client dal workflow. In un servizio reale, la funzione qui sopra appartiene a un modulo client leggero; code, archiviazione e retry si trovano nello strato superiore.
Se stai già usando httpx o un framework asincrono, la conversione è meccanica: payload e header sono identici.
Leggere la risposta
La risposta è JSON. Considerala una piccola busta che riguarda due cose: se l'attività è riuscita e dove si trova l'output.
In generale, dovresti verificare:
- Lo stato del trasporto. Un 2xx significa che la richiesta è stata accettata ed elaborata. Un 4xx indica che la tua richiesta è errata; un 5xx che c'è stato un problema lato server. Registra il codice di stato a ogni chiamata: è l'osservabilità più economica che puoi aggiungere.
- I campi del corpo della risposta. Il payload contiene il risultato generato. Il risultato immagine viene restituito come URL che punta all'asset generato. I nomi esatti dei campi dipendono dallo schema di risposta del modello; analizza in modo difensivo invece di assumere che sia una singola stringa.
- I metadati. Qualsiasi campo di utilizzo o durata nella risposta vale la pena catturarlo. La fatturazione è misurata dalla piattaforma, quindi persistere i metadati per richiesta ti permette in seguito di riconciliare i tuoi log con la dashboard.
Un'analisi robusta è la seguente:
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}")
Come gestire il risultato
L'URL restituito è un asset generato, non un asset permanente. Non passarlo direttamente al frontend e dimenticartene. Invece:
- Scarica e ri-ospita. Recupera subito i byte e scrivili nel tuo bucket con chiavi content-addressed. Questo disaccoppia il tuo prodotto dalla politica di conservazione del generatore.
- Registra la provenienza. Archivia gli URL di input, l'identificatore del modello e il timestamp insieme all'output. Quando un commerciante chiederà perché un certo try-on è venuto così, avrai bisogno di riprodurre l'attività esatta.
- Normalizza il formato. Ridimensiona e converti una volta sola al momento dell'ingestione nel formato standard della vetrina, invece di farlo a ogni visualizzazione di pagina.
Trattare la risposta come una consegna temporanea — analizza, scarica, archivia, scarta — è il modello scalabile.
Modalità di errore e strategia di retry
Non tutti gli errori meritano un retry. Riprovare ciecamente trasforma un piccolo hiccup a monte in una coda piena di attività duplicate e in una fattura sorprendente.
Classifica prima di riprovare
Non riprovare — correggi la richiesta:
- Errori di validazione di tipo
400: JSON malformato, campi mancanti o con nomi errati, corpo della richiesta non conforme alla struttura attesa dal modello. 401/403: API key errata o mancante, oppure la chiave non ha accesso a quel modello. Riprovare non serve mai.404: identificatore del modello o percorso dell'endpoint errato.- URL di immagini non raggiungibili. Se l'URL della persona o del capo restituisce 404 o va in timeout durante il recupero, la generazione non può proseguire. Verifica gli URL prima di inviare.
Riprova con backoff:
429: sei stato limitato. Fai backoff e rispetta il segnale.5xx: errore transitorio del servizio o a monte.- Guasti a livello di rete: reset della connessione, timeout in lettura.
Retry limitati con jitter
Limita il numero di tentativi — tre è un limite comune — e usa un backoff esponenziale con jitter casuale, così un gruppo di worker non riprova in sincrono:
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))
Misure di protezione in produzione
- Idempotenza a livello di attività. Esegui l'hash della coppia di URL di input come chiave dell'attività. Se la stessa chiave è già in esecuzione o completata, restituisci il risultato archiviato invece di reinviare.
- Coda di messaggi morti. Dopo l'esaurimento dei retry, parcheggia l'attività con il suo contesto completo invece di scartarla silenziosamente.
- Circuit breaker. Se il tasso di errore supera la soglia, smetti di inviare per un periodo di raffreddamento, invece di continuare a martellare un servizio in difficoltà.
- Avvisa in base alla forma, non solo alla quantità. Un picco di 4xx dopo un deployment di solito significa che qualcuno ha rinominato un campo.
Valida presto gli input
La maggior parte dei "guasti del modello" sono in realtà input scadenti. Fai un controllo preliminare economico: invia una richiesta HEAD a ogni URL, verifica il content type e le dimensioni approssimative e rifiuta gli asset manifestamente inutilizzabili prima di spendere una chiamata a consumo. Questa singola abitudine elimina gran parte del tuo traffico di retry.
Integrarlo in una pipeline reale
Una chiamata curl riuscita è solo una dimostrazione. Una funzionalità di prodotto affidabile richiede un po' più di struttura intorno.
Struttura il flusso in fasi
Una scomposizione praticabile:
- Ingestione. Un commerciante o un utente interno invia l'immagine della persona e quella del capo. Archivia entrambe nel tuo object storage e genera URL stabili e firmati.
- Validazione. Controlla raggiungibilità, formato e dimensioni. Rifiuta presto con un messaggio chiaro.
- Invio. Chiama
google-virtual-try-ontramite il modulo client. Registra nel database la chiave dell'attività, l'identificatore del modello e gli URL di input. - Materializzazione. In caso di successo, scarica l'immagine generata, convertila nel tuo formato standard e scrivila nella tua CDN con una chiave deterministica.
- Pubblicazione. Aggiorna il record dell'attività per puntare all'asset che ospiti tu e fai leggere alla vetrina solo dal tuo storage.
Ogni fase è riprovabile in modo indipendente: è proprio questo che rende l'intero sistema debuggabile. Se il passaggio 4 fallisce, non devi rieseguire la generazione.
Mantieni il client leggero
Metti la chiamata HTTP in un piccolo modulo e disponi la policy (retry, concorrenza, timeout, logging) intorno. Quando HiAPI aggiunge parametri a un modello, o quando vuoi fare A/B test su percorsi di generazione di immagini diversi, devi modificare un solo file.
Abitudini operative da adottare
- Asincrono per impostazione predefinita. La generazione richiede secondi, a volte di più. Invia da un worker, non dal gestore di richieste da cui l'utente è in attesa.
- Cache aggressiva. La stessa coppia persona più capo non dovrebbe mai essere generata due volte. Usa indirizzamento basato sul contenuto per gli output e controlla prima di inviare.
- Fai budget con visibilità. Poiché l'utilizzo è misurato dalla piattaforma, registra i metadati per richiesta e riconcilia periodicamente con la tua dashboard HiAPI. Scopri un loop di retry fuori controllo in poche ore, non a fine mese.
- Versiona prompt e parametri. Archivia l'oggetto dei parametri con ogni attività, così puoi riprodurre i risultati dopo una modifica.
- Fallisci in modo visibile all'utente. Un'animazione di caricamento che non scompare mai è peggio di un onesto "non riusciamo a generare questo, prova con un'altra foto".
Prossimi passi
La stessa forma di richiesta vale per gli altri modelli di immagini HiAPI, quindi il client che costruisci qui diventerà il modello per il resto della tua pipeline. Una volta che la chiamata a due immagini è stabile, esplora il catalogo dei modelli per vedere cos'altro si adatta al tuo workflow: autenticazione, gestione degli errori e schemi di archiviazione restano identici.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business