Generare immagini di prodotto e-commerce con qwen-image-2.1-pro: utilizzo delle API e ricette di prompt

Perché vale la pena scegliere qwen-image-2.1-pro per le immagini di prodotto e-commerce

Il lavoro sulle immagini e-commerce raramente consiste in una sola cosa. Può essere uno scatto di catalogo per un nuovo SKU, un ritaglio per la pagina prodotto di un marketplace, un'immagine lifestyle per una landing page, e poi un banner con un'etichetta promozionale — spesso tutto da consegnare nella stessa settimana. Ciò che rende qwen-image-2.1-pro degno di valutazione è che, quando il tuo flusso di lavoro deve produrre tutto quanto sopra partendo dagli stessi dati di prodotto, riesce a gestire generazione, modifica di asset esistenti, output PNG trasparenti e rendering del testo nell'immagine in un unico modello, invece di dipendere da una catena di strumenti specializzati.

Tre tipologie di attività coprono la maggior parte del carico di lavoro:

• Ritaglio trasparente — il prodotto è separato in modo pulito su uno sfondo trasparente, pronto per essere inserito in qualsiasi posizione del CMS.
• Composizione in scena — il prodotto è collocato in un ambiente lifestyle o in studio credibile, generato da una descrizione testuale più un'immagine di riferimento.
• Layout con testo — etichette, badge angolari e banner, dove il testo deve essere chiaramente leggibile e posizionato correttamente.

Dove non può sostituire lo studio fotografico: per le immagini hero con requisiti di illuminazione di marca rigorosi, e per qualsiasi asset in cui la geometria del prodotto sia vincolata da normative (ad esempio imballaggi regolamentati). Considera la generazione come un mezzo per ampliare la copertura e accelerare le iterazioni, mantenendo poi un punto di approvazione umana — è proprio a questo che serve il processo di revisione descritto più avanti in questa guida.

La ragione pratica per prendere una decisione presto è l'architettura dei prompt. Se sai fin dall'inizio che lo stesso modello dovrà servire ritagli, scene e layout testuali, puoi creare un piccolo insieme di template di prompt con numeri di versione, invece di scrivere prompt al volo a ogni richiesta. Questa decisione non costa nulla all'inizio, ma evita di dover rifare il lavoro in seguito.

Richieste eseguibili: curl e Python

Prima di progettare i prompt, ottieni con successo un'immagine. Su HiAPI la forma delle richieste è coerente tra i modelli: una chiave API, un nome di modello e i parametri di input nel corpo della richiesta. Il parametro minimo richiesto da qwen-image-2.1-pro è il prompt, più l'immagine di input che vuoi modificare se il compito è una modifica anziché una generazione da zero.

curl

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "Foto di prodotto in studio di una tazza da caffè in ceramica nera opaca, vista a tre quarti, luce principale morbida e diffusa da sinistra, leggero riflesso su uno sfondo senza giunture grigio chiaro, senza testo",
    "size": "1024x1024"
  }'

Python requests

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-2.1-pro",
        "prompt": "Foto di prodotto in studio di una tazza da caffè in ceramica nera opaca, "
                  "vista a tre quarti, luce principale morbida e diffusa da sinistra, "
                  "leggero riflesso su uno sfondo senza giunture grigio chiaro, senza testo",
        "size": "1024x1024",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

Vale la pena adottare due abitudini in questa fase. Primo, leggi la chiave API dalle variabili d'ambiente, non codificarla mai direttamente — la eseguirai presto da un job batch. Secondo, conserva il corpo completo della risposta nei log, inclusi eventuali campi di utilizzo restituiti dall'endpoint; è proprio questa la base che userai in seguito per misurare il "costo per asset approvato", invece di tirare a indovinare.

Esegui prima una richiesta con un prompt generico come quello sopra. Verifica di aver ottenuto l'immagine e che la struttura della risposta corrisponda alle aspettative del codice a valle. Solo allora passa alle ricette — la progettazione dei prompt richiede tempo, e non vorrai scoprire problemi di pipeline a metà strada.

Ricette di prompt per PNG trasparenti e scene di prodotto

I prompt estemporanei tendono a divergere. I team di catalogo ottengono risultati coerenti mantenendo un piccolo insieme di template con slot variabili espliciti, versionandoli nel repository insieme al codice che chiama l'API, e sostituendo gli slot per singolo SKU a ogni esecuzione.

Ricetta 1: ritaglio trasparente

Ritaglio del prodotto {product_name}, {distinguishing_detail}, completamente isolato su sfondo trasparente.
Vista {view_angle}, prodotto centrato e interamente inquadrato, con un piccolo margine tutto intorno.
Illuminazione da studio morbida e uniforme, nessuna ombra netta proiettata sullo sfondo, solo una leggera ombra di contatto direttamente sotto il prodotto.
Fotorealistico, bordi nitidi, senza testo, senza oggetti di scena, senza elementi di sfondo.

Slot: {product_name} ("una tazza da caffè in ceramica nera opaca"), {distinguishing_detail} ("lo spessore visibile del bordo e un piccolo manico"), {view_angle} ("a tre quarti", "frontale", "dall'alto"). Le clausole sulla trasparenza e sul "non proiettare ombre sullo sfondo" vanno mantenute così come sono; sono queste due righe a fare la maggior parte del lavoro nei compiti di ritaglio.

Ricetta 2: scena lifestyle

Foto di prodotto lifestyle di {product_name} in {scene_description}.
Il prodotto è il soggetto: messa a fuoco nitida, proporzioni corrette, {brand_color_note}.
{lighting_note}. Profondità di campo ridotta, sfondo sfocato in modo morbido.
Stile naturale ed editoriale. Senza testo, senza loghi, nessun marchio visibile sullo sfondo.

Slot: {scene_description} ("un luminoso piano di lavoro da cucina minimalista, con un tovagliolo di lino e una finestra del mattino"), {brand_color_note} ("colori non alterati, nessuna dominante applicata"), {lighting_note} ("calda luce direzionale del mattino da destra").

Ricetta 3: hero da studio

Foto di prodotto in studio di {product_name}, vista {view_angle}.
{background_description}. Luce principale da {key_light_direction}, schiarita morbida, riflessi controllati.
Fotorealistico, materiali e texture superficiali dettagliati. Senza testo.

Due regole mantengono sana la libreria di template. Non modificare mai un template direttamente nello script — modifica il file del template, incrementa il numero di versione e rigenera. E registra da quale versione della ricetta proviene ogni asset approvato, così quando un template cambia puoi capire se le vecchie approvazioni restano valide.

Modificare immagini di prodotto esistenti

Le richieste di modifica sono dove si verificano la maggior parte dei problemi di qualità, perché un prompt vago porta il modello a rigenerare il prodotto invece di modificare la scena attorno ad esso. Suddividi ogni prompt di modifica in tre parti esplicite:

1. Cosa cambiare — scena, sfondo, illuminazione o oggetti di scena aggiunti.
2. Cosa conservare — forma, proporzioni, motivo dell'etichetta, materiale e colore del prodotto.
3. Cosa evitare — nuovo testo, nuovi loghi, geometrie distorte, parti duplicate.

Un template utilizzabile:

Modifica questa foto di prodotto.
Cambia: sostituisci lo sfondo con {new_background}; modifica l'illuminazione in {new_lighting}.
Conserva: la forma esatta, le proporzioni, il materiale superficiale del prodotto e qualsiasi motivo di etichetta, esattamente come sono.
Non: aggiungere testo, aggiungere loghi, cambiare il colore del prodotto o alterarne la geometria.
Risultato fotorealistico, che sembri uno scatto continuo.

Esempio di compilazione: {new_background} = "uno sfondo senza giunture grigio caldo e pulito", {new_lighting} = "morbida luce diffusa dall'alto, con una leggera sfumatura dietro il prodotto".

Le clausole di conservazione non sono una garanzia. Le modifiche lunghe — sostituzione dello sfondo, regolazione dell'illuminazione e aggiunta di oggetti di scena in un unico prompt — danno al modello più spazio per divergere sul prodotto stesso. Suddividile: prima la sostituzione dello sfondo, verificala, poi applica le modifiche secondarie su un risultato intermedio approvato. Ogni fase è un confronto che chi rivede può effettivamente valutare.

Mantieni inoltre un'immagine di riferimento standard per ogni SKU. Quando chi rivede è incerto se il prodotto sia cambiato, il riferimento è la verità di base, non il risultato della generazione precedente.

Rendering del testo e controllo del layout

Il testo nell'immagine è la funzione che più facilmente delude quando si improvvisano i prompt. Il testo che deve comparire nell'asset finale va racchiuso tra virgolette, posizionato e vincolato.

Banner e-commerce per {product_name}.
Layout: prodotto nel terzo destro, blocco di testo nel terzo sinistro, margini ampi.
Testo: renderizza accuratamente "{headline}" in un font sans-serif in grassetto come titolo principale, e sotto di esso renderizza accuratamente "{subline}" con un peso più leggero.
Stile: {color_scheme}, pulito e moderno, alto contrasto per la leggibilità.
Nessun testo deve comparire in qualsiasi altra posizione dell'immagine. Tutte le parole scritte esattamente come indicato.

Perché ogni riga conta:

• Testo tra virgolette più un'istruzione esplicita di "accuratezza" riduce riscritture e parole inventate.
• Posizione e proporzione ("terzo destro", "terzo sinistro") impediscono al modello di seppellire il prodotto sotto il titolo.
• "Nessun testo deve comparire in qualsiasi altra posizione dell'immagine" è la clausola che sopprime la modalità di errore più comune: testo di riempimento plausibile agli angoli.
• Un titolo breve più un sottotitolo breve è molto più affidabile di un paragrafo di testo. Se il tuo layout richiede un blocco di copy, genera prima l'immagine senza quel copy, poi impagina il copy nel CMS o nello strumento di design.

Per i badge e le etichette (un'etichetta "New", un'indicazione di taglia), trattali come piccoli prompt a sé stanti, invece di aggiungerli all'immagine hero — un piccolo prompt per un badge con una singola parola tra virgolette è molto più facile da verificare in fase di revisione rispetto a un banner intero. Controlla sempre l'ortografia a piena risoluzione prima dell'approvazione; un errore di testo è economico da individuare e costoso da correggere online.

Revisione dell'output: confronto e ciclo di approvazione

Gli asset generati non dovrebbero arrivare in negozio senza uno sguardo umano. Il ciclo più economico e affidabile è il confronto prima/dopo asset per asset: metti la foto di input (o le specifiche nel caso di una generazione da zero) accanto all'output generato, e registra la versione della ricetta del prompt e i valori delle variabili.

Un ciclo praticabile per un piccolo team:

1. Genera un piccolo batch — qualche variante per SKU, non l'intero catalogo.
2. Prepara una tabella di confronto affiancato: a sinistra l'immagine sorgente, a destra la candidata, con il prompt registrato sotto.
3. Rivedi con una checklist breve e fissa: forma del prodotto invariata, motivo dell'etichetta intatto, sfondo pulito, testo scritto correttamente, margini adeguati.
4. Contrassegna ogni candidata come approvata o rifiutata, e registra la versione della ricetta che ha prodotto il risultato approvato.
5. Solo a questo punto estendi all'intero batch, riutilizzando la ricetta approvata. Se la ricetta cambia dopo l'approvazione, considera le approvazioni esistenti valide solo provvisoriamente finché non vengono ricontrollate.

Mantieni la checklist breve e identica ogni volta. Una checklist coerente di quattro voci individua più problemi rispetto a un modulo lungo eseguito in modo irregolare. Conserva anche le candidate rifiutate — sono la prova del perché una versione della ricetta sia stata scartata, ed evitano alla persona successiva di riscoprire gli stessi errori.

Questo ciclo è anche il tuo strumento di controllo dei costi. Poiché le approvazioni sono legate alla ricetta, puoi calcolare quante generazioni servono per ogni asset approvato e iterare sui template che consumano il maggior numero di tentativi.

Considerazioni su costi, latenza ed elaborazione batch

Pianifica in base alle tue misurazioni, non a supposizioni. Per i modelli di immagine su HiAPI la fatturazione è per immagine prodotta, quindi la variabile che domina la spesa è il "numero di tentativi per asset approvato" — che dipende interamente dalla qualità dei prompt e dal rigore della revisione. Il prezzo attuale per immagine è sulla pagina dei prezzi del sito; non inserire cifre fisse nel codice o nei documenti di budget.

Un metodo di lavoro ragionevole:

• Misura una baseline. Esegui dieci SKU con una ricetta approvata, conta le generazioni totali e le approvazioni totali, e ricava il numero di tentativi per asset approvato. Questo rapporto dice più di qualsiasi benchmark.
• Itera singolarmente, elabora in batch dopo l'approvazione. L'iterazione dei prompt va fatta un'immagine alla volta. Dopo che una ricetta è approvata, passa all'elaborazione batch con una concorrenza moderata e una strategia di retry che registri gli errori invece di ripetere in silenzio la fatturazione.
• Tratta la latenza come un parametro di pianificazione. La generazione di immagini si misura in secondi, non in millisecondi. Avvia i job in modo asincrono, scrivi i risultati in una coda, e lascia che chi rivede li elabori dalla coda invece di bloccarsi a ogni chiamata.
• Fai il budget sul rapporto, non sul prezzo unitario. Una volta che hai il numero di tentativi per asset approvato, la stima del catalogo è semplice aritmetica basata sulle tue misurazioni.

Un'ultima buona abitudine: versiona le tue ricette e registra la versione della ricetta in ogni richiesta. Costa un solo campo, ma trasforma "perché questo asset il mese scorso sembrava diverso?" da un'indagine in una query.

Costruisci il flusso minimo che ti consenta di gestire ritagli, scene e layout testuali tramite l'API, mantieni versionata la libreria dei prompt, e lascia che sia il ciclo di revisione — non la speranza — a decidere cosa può andare online.