Accesso all'API Google Virtual Try-On: immagine della persona e immagine del capo

Inserendo ciascuna delle due immagini nel campo corretto, l'integrazione parte da una base chiara. La foto della persona va in person_image_url, l'immagine del capo in product_image_url; inserire la foto della persona nel campo del capo cambia il significato dell'input del task.

TL;DR

Google Virtual Try-On costa $0.1075 per immagine; consulta prezzi e budget. Usa l'endpoint /v1/tasks di HiAPI: invia il task e ottieni un taskId, poi interroga il risultato. Nessun prompt necessario.

Preparazione degli input e campi

Scegli una foto frontale di una sola persona, con il contorno del corpo il più possibile chiaro; per il capo usa un'immagine distesa o appesa, con sfondo pulito e bordi completi. I due URL permanenti delle immagini nell'esempio seguente corrispondono rispettivamente alla persona A e a una T-shirt a righe rosse e bianche, e possono essere sostituiti con i tuoi URL di immagini pubbliche.

Campo	Come compilarlo
person_image_url	Obbligatorio; URL HTTP(S) pubblico della foto della persona
product_image_url	Obbligatorio; URL HTTP(S) pubblico dell'immagine del capo
num_images	Numero intero; compila esplicitamente 1, attualmente è supportata una sola immagine

Mappare le combinazioni di business sulla richiesta

Per provare capi diversi sulla stessa persona, mantieni fisso person_image_url e sostituisci product_image_url capo per capo; per mostrare lo stesso capo su persone diverse, mantieni fissa l'immagine del prodotto e sostituisci quella della persona. Per più candidati con lo stesso set di immagini, conserva i due input e invia richieste separate, compilando ogni volta num_images: 1. Si consiglia di salvare nei propri registri dei task il codice prodotto e la versione dell'immagine della persona, senza indovinare la corrispondenza solo dal nome del file di risultato.

Sia la persona sia il capo devono essere forniti tramite URL HTTP(S) leggibili pubblicamente; non sono supportati percorsi su disco locale o data URI come URL di immagine. Il fatto che un'immagine sia visibile nel browser con sessione attiva non significa che altri servizi possano leggerla; prima dell'invio verifica il link in condizioni che non dipendano da una sessione autenticata. Si consiglia di verificare che venga restituita l'immagine stessa, non una pagina di galleria o di avviso permessi, e di mantenere l'immagine accessibile durante la lettura del task.

Se la foto della persona copre l'orlo del capo o le mani si sovrappongono ampiamente al vestito, valuta prima una foto con contorni più chiari. Per l'immagine del capo preferisci un'immagine distesa o appesa di un singolo capo con bordi completi, evitando di usare come immagine prodotto indipendente un risultato di outfit già indossato. I campi pubblici non offrono impostazioni per la protezione locale, la regolazione dei polsini o il blocco delle scarpe; non è possibile esprimere tali richieste aggiungendo campi personalizzati.

Scegliere immagini chiare è un metodo di lavoro: la capacità dell'API di accettare le immagini e l'accuratezza della rappresentazione del prodotto vanno verificate separatamente. Questo articolo non aggiunge per Try-On promesse su dimensioni dei file, limiti di pixel o dimensioni di output non documentati; non è possibile applicare direttamente i limiti di input di altri modelli di immagine.

Invio del task: cURL

Di seguito un esempio Bash/cURL. Configura prima HIAPI_API_KEY nell'ambiente di esecuzione; gli URL delle immagini nella richiesta possono essere sostituiti, mentre la chiave resta nell'ambiente lato server.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

Un invio riuscito restituisce data.taskId. Salva questo valore per le interrogazioni successive.

Interrogazione del task e salvataggio dei risultati

Inserisci l'ID del task in TASK_ID e interroga:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Quando il task ha data.status=success, ottieni l'immagine da data.output[0].url e salvala. Per attività in esecuzione continua, puoi impostare al livello superiore della richiesta di invio callback.url e callback.when: "final" per ricevere la notifica di completamento, deduplicando per taskId; la notifica può essere attivata sia in caso di successo sia di fallimento. L'interrogazione è adatta al debug e alle verifiche successive.

Polling, callback e gestione dei timeout

Invio e interrogazione sono due cose distinte. Dopo aver ottenuto data.taskId, registralo insieme agli input di questa esecuzione, poi interroga con GET /v1/tasks/:id. Se non è ancora entrato nello stato finale, continua ad attendere e non sostituire l'interrogazione con un nuovo POST. L'intervallo di polling e il limite di attesa lato business sono stabiliti dalla tua applicazione; questo articolo non fornisce tempi medi o limiti fissi di completamento su cui basare promesse; anche i timeout di rete nell'esempio non costituiscono una garanzia sulla durata del servizio.

Il timeout di una richiesta di interrogazione indica solo che questa lettura non è stata completata in tempo. Conserva l'ID del task e riprova più tardi lo stesso task. Se il timeout riguarda la richiesta di invio stessa e non hai ottenuto l'ID, c'è incertezza sul fatto che il server abbia già accettato il task: conserva orario di invio e contenuto della richiesta, verifica prima i registri dei task e poi decidi se reinviare. Non interpretare direttamente un'eccezione del client come fallimento del task e non promettere che richieste ripetute vengano unite automaticamente.

La configurazione della callback va al livello superiore del corpo della richiesta, allo stesso livello di model e input, e non può essere inserita nell'input del modello. Quando configuri callback.url, usa anche callback.when: "final". La notifica di completamento può corrispondere a un successo o a un fallimento, quindi dopo la ricezione controlla comunque lo stato. Interrogazione e callback possono riguardare lo stesso task: il lato business deve deduplicare per taskId, evitando download o attivazioni successive ripetute. Qui si descrive il metodo di gestione lato applicazione, senza presupporre che la callback arrivi entro un certo tempo.

Dopo data.status=success, verifica che data.output contenga effettivamente un indirizzo di risultato leggibile, poi scarica l'immagine. Se viene restituito fail, salva il messaggio di errore e correggi la richiesta in base al contenuto; non limitarti a dedurre da un solo stato che la causa sia un'immagine troppo grande, un guasto di rete o altro motivo specifico. In caso di stato imprevisto o output mancante, conserva la risposta e verifica di nuovo, senza trattare un risultato vuoto come consegna riuscita.

Anche il fallimento del download e quello della generazione vanno distinti. Se il task è riuscito ma il file non è stato salvato correttamente, rileggi o scarica prima il risultato esistente, evitando di rifare subito l'immagine. In archiviazione conserva ID del task, corrispondenza degli input e posizione finale del file, così da poter identificare con precisione da quale richiesta proviene ogni immagine. Il messaggio "timeout di attesa" mostrato all'utente deve indicare che l'interfaccia corrente ha smesso di attendere, non dichiarare arbitrariamente che il task lato server è stato annullato.

Esempio di invio in Python

L'ambiente deve avere installato requests. Qui timeout=60 è il limite di attesa della richiesta di rete lato client, non il tempo di generazione dell'immagine.

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

Controlli prima dell'invio e sui risultati

L'API non richiede prompt. Non impostare num_images a 2 o 4; se servono immagini candidate, invia richieste separate. Prima dell'invio verifica che entrambe le immagini siano leggibili pubblicamente e che i campi non siano invertiti. Se ricevi uno stato di fallimento, leggi il messaggio restituito e correggi l'input, senza reinviare identico più volte.

Validare le immagini restituite in base all'uso del prodotto

Confronta prima il risultato con l'immagine della persona, controllando viso, capelli, postura, sfondo e i pantaloni e le scarpe che non dovrebbero cambiare. Poi confronta con l'immagine del capo verificando colore, tipo di scollo, lunghezza delle maniche, motivo e orlo. Per una T-shirt a righe, controlla come le righe orizzontali si collegano sul petto e sulle maniche; per un vestito, le bretelle, lo scollo drappeggiato e le pieghe vicino alle mani; per una camicia, se i polsini sono arrotolati e se l'orlo è infilato nei pantaloni. Questi controlli derivano dalle variazioni visibili nei casi e non garantiscono che altri input producano solo queste differenze.

"File scaricato" e "immagine utilizzabile in una pagina prodotto" vanno registrati separatamente. Anche dopo un esito positivo possono comparire variazioni al di fuori del capo; lo stato dell'API non può sostituire automaticamente la validazione umana. Se il difetto deriva da occlusioni nell'input, cambia prima l'input e riprova; se il prodotto deve mostrare una specifica lunghezza delle maniche o accessori fissi, valuta prima se il risultato attuale soddisfa tale vincolo, senza ignorare i dettagli del prodotto solo perché l'outfit complessivo è naturale.

Quando aggiungi candidati allo stesso set di input, conserva i risultati precedenti per il confronto, senza sovrascrivere i vecchi file con quelli nuovi. Al momento della scelta, annota i motivi di accettazione o rifiuto, per agevolare la gestione futura di prodotti simili. Le immagini servono solo a osservare l'aspetto; per taglie reali e sensazione al piede o addosso servono comunque le misure del capo e informazioni da una prova su persona reale.

Domande frequenti

La foto della persona e l'immagine del capo possono usare lo stesso campo?

No. La foto della persona va in person_image_url, l'immagine del capo in product_image_url.

Serve aggiungere il parametro prompt?

No. L'API non ha un campo prompt; il try-on è determinato dalle due immagini di input.

Perché scrivere esplicitamente num_images: 1?

Attualmente è supportata una sola immagine di risultato; scriverlo esplicitamente permette di far corrispondere direttamente il numero di immagini richieste al budget di $0.1075 per immagine.

Basta ottenere taskId per leggere l'immagine?

Occorre anche interrogare il task o ricevere la notifica; dopo che il task ha data.status=success, ottieni l'immagine da data.output[0].url.

Letture successive

Prezzi e budget · Integrazione API · Casi e scelta delle immagini · Google Virtual Try-On

Se devi scegliere tra il try-on di abiti e un metodo generico di modifica delle immagini, consulta il confronto tra Google Virtual Try-On e Seedream 5.0 Lite, che esamina punto per punto capo, scarpe e aspetto della persona.