Guida all'uso
Generare immagini di prodotto e-commerce con qwen-image-2.1-turbo tramite l'API HiAPI
Un flusso di lavoro rapido per immagini di catalogo per sviluppatori: output PNG trasparente e richieste API eseguibili
In questa pagina
Quando usare qwen-image-2.1-turbo
Il lavoro visivo di un catalogo prodotti è in apparenza un problema creativo, ma in sostanza è un problema di throughput. Una singola immagine principale può essere ritoccata a mano, ma un negozio con migliaia di SKU richiede composizioni coerenti, tempi di consegna prevedibili e output che si inseriscano direttamente nella pipeline di asset esistente. Il modello di immagine che scegli determina quanta pipeline devi ricostruire.
In genere tre criteri guidano questa decisione:
- Latenza sotto carico. Le attività notturne di catalogo sono attività batch; un modello che si comporta bene in scenari interattivi può comunque rendere doloroso un aggiornamento di 10.000 SKU.
- Idoneità del formato di output. Se la tua fase di compositing richiede un canale alpha e il modello restituisce solo immagini opache, devi aggiungere tu stesso un passaggio di segmentazione.
- Comportamento sui prompt nel linguaggio delle descrizioni di prodotto. I prompt di prodotto sono brevi, specifici e ripetitivi; un modello che li gestisce in modo affidabile batte un modello che eccelle su prompt artistici aperti.
Questa guida si concentra sui primi due criteri e sul pattern di richiesta che li collega. Esamineremo come la variante turbo si posiziona in una pipeline di immagini di prodotto, come l'output PNG trasparente cambia la tua catena di post-elaborazione e forniremo una richiesta pronta da inserire in un worker. Infine discuteremo cosa considerare quando si scala in batch e confronteremo brevemente l'approccio image-to-image per i casi in cui la generazione guidata dal testo non è adatta.

Output PNG trasparente e la tua catena di post-elaborazione
Puoi pensare alla pipeline di immagini di prodotto come a quattro fasi: costruzione della richiesta → generazione → elaborazione dell'output → pubblicazione. La variante turbo è una scommessa deliberata: rendere la seconda fase abbastanza veloce ed economica da sostenere la scala del catalogo, così da poter investire il budget di engineering nella prima e nella terza fase.
Quando è la scelta giusta come prima opzione
Scegli qwen-image-2.1-turbo quando:
- I tuoi prompt sono strutturati e ripetibili: un template per categoria, con slot per materiale, colore, angolazione e intenzione di sfondo.
- Devi generare molte varianti per ogni SKU (angolazioni, palette, scene) invece di una singola immagine con una direzione artistica curata.
- Il tuo compositing a valle è già automatizzato, quindi un ritaglio pulito vale più di una scena completa e finita.
- Vuoi una baseline guidata dal testo prima di introdurre immagini di riferimento.
Quando serve un modello più potente
Se un SKU richiede una composizione molto specifica che deve corrispondere rigorosamente a una foto di riferimento, o se il collo di bottiglia è la qualità dell'output in scene complesse più che il volume, il livello turbo non è la scelta predefinita adatta. In questi casi, mantieni il turbo per la maggior parte delle varianti di catalogo e assegna il piccolo insieme di asset principali a un percorso di generazione più pesante: la forma della pipeline resta invariata, cambia solo l'identificatore del modello.
Progettare lo slot del modello come sostituibile
Poiché il livello turbo punta sulla scala, tratta il nome del modello come configurazione, non come costante hardcoded sparsa nel codice. Leggere una variabile d'ambiente IMAGE_MODEL all'avvio del worker significa poter fare A/B test di un altro modello su alcune categorie senza modificare il codice della richiesta. È proprio questa decisione a rendere portabile il resto della guida.

Una richiesta HiAPI eseguibile per immagini di prodotto
Il PNG trasparente è la scelta di output con il maggiore effetto leva nelle pipeline di catalogo, perché sposta il passaggio costoso, ovvero separare il prodotto dallo sfondo, nella fase di generazione. Non devi più segmentare un rendering opaco: ricevi un asset con canale alpha e lo componi tu stesso.
Cosa cambia a valle
Con un canale alpha, lo sfondo diventa una questione di rendering, non di modellazione. Lo stesso ritaglio può essere collocato su uno sfondo bianco da studio come immagine principale della PDP, in una scena lifestyle per un posizionamento marketing, o su un colore di brand puro come tile di categoria: tutto da una singola generazione. È questa l'economia centrale: un asset di prodotto, più varianti pubblicate.
In pratica, pianifica i seguenti passaggi:
- Verifica il canale alpha. Controlla che l'immagine abbia effettivamente un canale alpha non banale e che il soggetto non sia tagliato sul bordo dell'inquadratura. Un ritaglio che tocca il bordo è un fallimento della generazione, non un problema di compositing.
- Normalizza la tela. Prima del compositing, ridimensiona e riempi il ritaglio su una tela coerente, così che le posizioni dei diversi SKU siano prevedibili.
- Componi separatamente per ogni posizionamento di pubblicazione. Salva i preset di sfondo come dati (dimensioni, colore, eventuali asset di sfondo) e renderizza ogni posizionamento dallo stesso PNG sorgente.
- Archivia i file sorgente, pubblica i rendering. Persisti l'originale trasparente come asset canonico e tratta ogni variante composta come un artefatto derivato rigenerabile.
Attenzione al compromesso sulla dimensione dei file: il canale alpha rende i PNG più grandi, e l'archiviazione del catalogo moltiplica questo per ogni variante. Se la tua CDN serve WebP o AVIF, converti al momento della pubblicazione conservando il file PNG sorgente.

Scalare su attività batch ed evitare trappole di integrazione
Tutto quanto segue gira sull'interfaccia unificata di HiAPI: un unico URL di base, un'unica credenziale, una forma di richiesta coerente tra i modelli. Prima di fissare lo schema, recupera l'elenco esatto dei parametri e i nomi correnti dei campi dalla pagina del modello qwen-image-2.1-turbo; ciò che conta qui è il pattern stesso.
La forma della richiesta
La chiamata per un'immagine di prodotto è composta da un prompt e da specifiche di output. Costruisci il prompt con un template, così che ogni SKU fornisca solo le proprie variabili:
import os, requests
HIAPI_KEY = os.environ["HIAPI_API_KEY"]
MODEL = os.environ.get("IMAGE_MODEL", "qwen-image-2.1-turbo")
def product_prompt(sku):
return (
f"foto di prodotto in studio di {sku['name']}, {sku['material']}, "
f"finitura {sku['color']}, vista a tre quarti, illuminazione morbida e uniforme, "
"centrata su uno sfondo neutro, senza testo, senza oggetti di scena"
)
def generate(sku):
resp = requests.post(
"https://api.hiapi.ai/v1/images/generations",
headers={"Authorization": f"Bearer {HIAPI_KEY}"},
json={
"model": MODEL,
"prompt": product_prompt(sku),
"transparent_background": True,
"n": 1,
},
timeout=120,
)
resp.raise_for_status()
return resp.json()
Due note sul corpo della richiesta. Primo, richiedi esplicitamente lo sfondo trasparente: è un parametro della chiamata, non qualcosa da dedurre dopo il download. Secondo, mantieni basso il valore di n per ogni chiamata e parallelizza a livello di attività; il retry di un batch di richieste con singola immagine è molto più pulito di una richiesta di venti immagini, dove il fallimento di una sola fa perdere l'intero gruppo.
Gestire la risposta in modo difensivo
La risposta contiene i dati dell'immagine (URL o payload codificato, a seconda dei parametri inviati). Considera il recupero come un dominio di errore separato dalla generazione: dopo che la generazione ha restituito il risultato, scarica, valida e carica sul tuo storage. Da quel momento la tua pipeline fa riferimento al tuo bucket, non a un risultato temporaneo: è questo il punto che rende gestibili retry e ri-rendering.
Confronto con il percorso image-to-image
Il divario tra uno script eseguibile e un'attività di catalogo eseguibile si manifesta quasi sempre nelle parti noiose.
Templateizzare i prompt come dati
Metti i frammenti di prompt in file di configurazione per categoria, non nel codice. Ogni SKU fornisce gli slot; la categoria fornisce la struttura della frase e i vincoli negativi ("no text, no watermarks, no props"). Quando la composizione di una categoria è sbagliata, correggi un template invece di migliaia di righe di dati.
Riprovare con criterio
Distingui i fallimenti ritentabili (timeout, errori temporanei del server, limiti di frequenza) da quelli terminali (parametri non validi, prompt rifiutati). Per i primi usa backoff esponenziale e un limite di retry; per i secondi fallisci subito esponendo la causa, perché ritentare richieste malformate consuma solo la coda. Qui conta l'idempotenza: usa lo SKU più l'hash del prompt come chiave di ogni attività, così un'attività ritentata sovrascrive invece di duplicare.
Validare prima che sia visibile in vetrina
Inserisci un cancello di validazione tra generazione e pubblicazione. Controlli automatici a basso costo intercettano la maggior parte degli output scadenti:
- Il canale alpha è presente e il soggetto non è tagliato ai bordi.
- La risoluzione soddisfa il minimo richiesto dal posizionamento più grande che pubblichi.
- Un hash percettivo rispetto agli asset correnti segnala quasi-duplicati inattesi.
Invia ciò che non supera il cancello a una coda di revisione invece di scartarlo. I fallimenti silenziosi sono esattamente il modo in cui un catalogo si riempie in silenzio di prodotti del colore sbagliato.
Attenzione ai limiti di concorrenza
Le attività batch raggiungono i limiti di frequenza a raffiche, non gradualmente. Imposta la concorrenza dei worker sotto il limite che ritieni di avere, rendi quel limite configurabile e lascia che la coda assorba l'arretrato. Una pipeline limitata ma che completa il lavoro è meglio di una pipeline che oscilla avanti e indietro.
Budget basato sull'output, non sulla richiesta
La fatturazione segue l'output che generi, quindi tieni traccia del numero di asset generati per SKU come segnale di costo. Quando una categoria inizia a generare molte varianti per prodotto, deve essere una decisione consapevole di progettazione del prompt, non qualcosa che scopri in fattura.
Confronto con il percorso image-to-image
Quando per il prodotto non esiste ancora una foto utilizzabile (un nuovo SKU non ancora fotografato, un prodotto con un nuovo colore mai fotografato, o asset segnaposto per il lancio), la generazione guidata dal testo è la scelta predefinita corretta. Il prompt descrive completamente il risultato e l'output trasparente ti fornisce un asset compositabile senza passaggio di segmentazione.
Il percorso image-to-image inverte l'input. Fornisci un'immagine di riferimento e il modello lavora su di essa, ed è esattamente ciò che serve quando la fedeltà al prodotto reale non è negoziabile: cuciture reali, finiture hardware autentiche, la tonalità esatta che il cliente riceverà. In questa modalità, l'immagine di riferimento è il vincolo che mantiene onesta la generazione.
Per la maggior parte dei cataloghi, una divisione pratica:
- Testo-immagine turbo per la scala: varianti, sfondi, tile di categoria, immagini segnaposto per le prime pubblicazioni.
- Image-to-image per ogni caso in cui il cliente userà l'immagine per decidere l'acquisto e l'accuratezza visiva è cruciale.
Entrambi condividono lo stesso scheletro di pipeline, quindi il passaggio è solo un identificatore di modello più un campo di input, non una riscrittura. Quando ti serve un output guidato da un'immagine di riferimento, il modello image-to-image qwen-image-3.0 può essere collegato allo stesso worker, basta allegare l'immagine di riferimento accanto al prompt.
Esegui prima il percorso turbo su una categoria, misura il tasso di superamento della validazione, poi espandi gradualmente: la pagina del modello elenca i campi che devi integrare.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Guida introduttiva a Tripo H3.1: come scegliere tra tre modalità di input, parametri e prezzi
Guida pratica per sviluppatori: decisioni di integrazione e controllo dei costi nella generazione 3D
-
Guida all'uso
Utilizzare topaz-upscale/video tramite l'API HiAPI: flusso di lavoro per il miglioramento della qualità dei video brevi
Interpolazione dei fotogrammi, impostazioni di potenziamento e una richiesta HiAPI funzionante per video verticali
-
Guida all'uso
Generare immagini di prodotti e-commerce con l'API HiAPI e gpt-image-2.5-sunburst/image-to-image
Immagini di riferimento, sostituzione dello sfondo, scene d'uso e una richiesta HiAPI funzionante