Immagini di prodotto e-commerce con Imagen 4: prompt, codice batch e controllo qualità

Panoramica

• La versione standard di Imagen 4 funziona su HiAPI con l'id imagen-4.0, al prezzo di $0.06 per immagine, genera un'immagine per richiesta e supporta solo la generazione testo-immagine. Apri la pagina del modello Imagen 4 per provare subito un prompt.
• Per i cataloghi di prodotti è ideale per generare immagini di prodotto su sfondo bianco e immagini in contesto lifestyle, che altrimenti richiederebbero un servizio fotografico dedicato per ogni variante colore. Non può riprodurre il tuo SKU reale, perché non accetta immagini di riferimento in input.
• aspect_ratio è un campo obbligatorio (senza valore predefinito), mentre seed deve essere una stringa numerica. Nei nostri test, "seed": "sku-dripper-01" ha superato la validazione, ma dopo circa un secondo ogni task è fallito con TASK_FAILED.
• Prevedi una fase di controllo qualità. In un batch di 4 immagini abbiamo ottenuto una caraffa di vetro non richiesta, una smaltatura lucida dove era richiesta una finitura opaca e testo falso sulle etichette degli oggetti di scena, nonostante l'impostazione negative_prompt: "text, logo".

Cosa copre questa guida

Si tratta di un flusso di lavoro pratico per negozi online, pensato per generare un set di immagini per una linea di prodotti: un'immagine catalogo su sfondo bianco per ogni SKU, un'immagine lifestyle per la pagina prodotto e un ritaglio verticale per le storie da mobile. Tutto quanto segue è stato eseguito il 2026-11-04 sull'API in produzione, usando un prodotto fittizio: un filtro da caffè in ceramica verde salvia con la sua tazza abbinata.

Se ti serve solo far funzionare la prima richiesta, inizia da Come usare l'API di Imagen 4. Per i modelli di prompt generici consulta Prompt per Imagen 4. Questa guida invece spiega come generare in batch set di immagini per il negozio e come verificarle prima della pubblicazione.

Scegli il livello prima di scrivere i prompt

I tre livelli di Imagen 4 su HiAPI sono tutti testo-immagine e condividono la stessa struttura di richiesta: basta cambiare l'id del model per passare da un livello all'altro. I prezzi provengono da Prezzi HiAPI del giorno del test.

Livello	Id modello	Prezzo per immagine	Pagina modello
Fast	imagen-4.0-fast	$0.03	Imagen 4 Fast
Standard	imagen-4.0	$0.06	Imagen 4
Ultra	imagen-4.0-ultra	$0.09	Imagen 4 Ultra

Per un catalogo prodotti l'aritmetica è semplice. 200 SKU × (1 immagine prodotto + 1 immagine lifestyle) = 400 immagini, pari a $24 con il livello standard, $12 con Fast e $36 con Ultra, senza contare eventuali nuovi tentativi. In questo articolo abbiamo testato solo il livello standard, quindi non facciamo alcuna affermazione sulla qualità di Fast o Ultra. Per il dettaglio completo dei prezzi consulta Prezzi dell'API Imagen 4.

La richiesta: quattro campi, due dei quali facili da sbagliare

Lo schema di input di imagen-4.0 è chiuso. Di seguito i casi limite che abbiamo incontrato costruendo il batch, con i messaggi di errore esatti:

Campo	Regola	Risultato osservato
prompt	Stringa obbligatoria	—
aspect_ratio	Obbligatorio, con uno dei valori 1:1, 16:9, 9:16, 3:4, 4:3, auto	Omesso: aspect_ratio: missing required field "aspect_ratio". "2:1": value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	Stringa opzionale	Accettato. Ha ridotto il testo sugli oggetti di scena, ma non lo ha eliminato (vedi controllo qualità)
seed	Stringa opzionale	Numero (12): seed: got number, want string. Stringa non numerica ("sku-dripper-01"): accettata con HTTP 200, poi il task termina con TASK_FAILED. Stringa numerica ("1042"): funziona correttamente
Qualsiasi altro contenuto	Rifiutato	additional properties 'foo' not allowed

Il problema del seed ci è costato un giro extra. Usare il codice SKU come seed per poter risalire alla generazione è allettante, e il validatore lo ha accettato. Tutti e quattro i task del nostro primo batch hanno restituito questo risultato:

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

Poi abbiamo rimosso i campi uno alla volta. Lo stesso prompt con solo negative_prompt è andato a buon fine, con solo "seed": "sku-dripper-01" è fallito, mentre con "seed": "1042" ha funzionato. Mantieni il seed numerico e conserva la mappatura degli SKU nella tua tabella dei task.

Le dimensioni di output dipendono dal rapporto. Nei nostri test, 1:1 ha restituito 1024×1024, 4:3 ha restituito 1152×864 e 9:16 ha restituito 720×1280, tutti in WebP. Se la tua vetrina richiede immagini ingrandite a 2000 px, pianifica una fase di upscaling. L'output da solo non è così grande.

Prompt per set di immagini da catalogo

Scrivi i modelli di prompt per tipo di scatto anziché per prodotto, poi inserisci la descrizione del prodotto. Mantieni illuminazione, angolazione della fotocamera e sfondo coerenti tra gli SKU, così che le immagini affiancate sembrino appartenere allo stesso catalogo.

Immagine prodotto (1:1). Specifica sfondo, composizione, direzione unica della luce e tipo di ombra desiderata:

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

Il risultato per la tazza è pulito: il manico è rivolto a destra come richiesto, l'ombra è morbida e lo sfondo uniforme. Nessuna modifica necessaria.

Immagine lifestyle (4:3). Specifica il soggetto, la superficie, la direzione della luce e quali oggetti di scena restano fuori fuoco. Poi ribadisci che il prodotto è il soggetto nitido:

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

Questo prompt ha generato l'immagine in cima all'articolo.

Immagine verticale per storie (9:16). Se in alto deve andare un titolo, chiedi esplicitamente spazio negativo:

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

Lo spazio vuoto nel terzo superiore è come richiesto. Ma nota che i chicchi interi di caffè sono dentro il filtro: nessuno prepara il caffè così, e chi compra caffè se ne accorgerebbe. Maggiori dettagli più avanti.

Codice di elaborazione batch asincrona

La generazione di immagini su HiAPI è asincrona: POST /v1/tasks restituisce un taskId, poi si interroga GET /v1/tasks/{taskId} finché lo status non è success o fail (vedi documentazione dell'API asincrona). Per un catalogo prodotti, invia tutti i task in una volta e interrogali in parallelo. Questo è lo script che abbiamo eseguito, con i prompt ridotti. Le due immagini di scena provengono direttamente da questo script. Le due immagini prodotto sono state generate una alla volta con gli stessi prompt durante la diagnosi del problema del seed (l'immagine prodotto del filtro è stata generata senza seed).

import os, time, json, concurrent.futures as cf
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
           "Content-Type": "application/json"}

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

In produzione tre dettagli sono importanti:

1. I task falliti restituiscono comunque HTTP 200. Controlla data.status == "fail" e data.error.code. Non affidarti solo a raise_for_status().
2. Scarica subito. output[0].url è un link temporaneo con un timestamp expireAt (nel nostro caso circa 7 giorni dopo). Copia i byte nel tuo storage o CDN. Non usare in hotlink quell'URL dalla tua vetrina.
3. Registra l'id del task accanto allo SKU. Quando un revisore rifiuta un'immagine, devi sapere quale prompt, seed e task id l'hanno generata.

Nei nostri test, un singolo task si è completato in 7–8 secondi lato server (created → completed). I due task di scena paralleli hanno impiegato 31 e 42 secondi di tempo reale, inclusi l'intervallo di polling di 4 secondi e il download. Con max_workers=4, nei batch piccoli il costo del polling domina rispetto al tempo di generazione.

Controllo qualità: cosa verificare prima di pubblicare le immagini

La generazione testo-immagine produce prodotti verosimili, non le foto dell'articolo che hai in magazzino. Ogni immagine va verificata, manualmente o automaticamente, rispetto allo SKU reale. Ecco i problemi che abbiamo trovato in un batch di 4 immagini:

Controllo	Risultato nel nostro batch	Come risolvere
Nell'immagine c'è solo il prodotto elencato	L'immagine prodotto del filtro ha aggiunto una caraffa di vetro verde abbinata con manico, mai richiesta nel prompt (vedi immagine sopra).	Aggiungi "single object, nothing else in frame" e riprova. Non pubblicare mai set che non vendi.
Finiture e materiali	Abbiamo chiesto una smaltatura "opaca". Entrambe le immagini del filtro sono risultate lucide. La tazza era più vicina a una finitura satinata.	Tratta i termini sui materiali come suggerimenti. Confronta con il prodotto reale e scarta ciò che non corrisponde.
Testo sugli oggetti di scena	Il sacchetto di caffè nella scena lifestyle presentava un segno simile a un logo e testo illeggibile sull'etichetta, nonostante l'impostazione negative_prompt: "text, logo".	Evita oggetti di scena con etichette nei prompt, oppure sfocali o ritagliali. Non lasciare mai testo falso nelle schede prodotto.
Logica del prodotto	L'immagine dall'alto mostrava chicchi interi di caffè dentro il filtro.	Fai revisionare le immagini di scena a qualcuno che conosce la categoria di prodotto.
Coerenza tra le immagini	Il motivo a nervature e la forma della base del filtro variavano tra immagine prodotto, immagine di scena e immagine dall'alto.	A meno che non corrispondano all'articolo reale, non mescolare immagini generate dello "stesso" SKU nella stessa pagina prodotto.
Dimensioni e proporzioni	Tutti gli output rispettavano il rapporto richiesto (1024², 1152×864, 720×1280).	Verifica automaticamente le dimensioni in pixel dopo il download.

L'ultimo punto è la decisione chiave per un negozio. Usa Imagen 4 per banner di categoria, immagini d'atmosfera lifestyle, creatività pubblicitarie e segnaposto per prodotti che esistono solo come specifiche. Per le foto di listino che devono mostrare esattamente il tuo articolo, parti da foto reali del prodotto e passa a un modello immagine-immagine. La nostra guida all'e-commerce con Seedream 4.5 immagine-immagine descrive quel flusso di lavoro nel dettaglio.

Domande frequenti

imagen-4.0 può inserire il mio prodotto reale in una nuova scena? No. Su HiAPI accetta solo prompt, aspect_ratio, negative_prompt e seed. Non c'è alcun campo per immagini in input, quindi non è possibile usare la foto del tuo prodotto come riferimento.

negative_prompt rimuove tutto il testo? Nei nostri test no. Vale la pena inviarlo, ma sugli oggetti di scena sullo sfondo delle scene lifestyle è comunque comparso testo falso sulle etichette. La soluzione affidabile è evitare oggetti di scena con etichette.

Perché il mio task fallisce subito con TASK_FAILED? Controlla prima il tuo seed. Stringhe non numeriche come "sku-dripper-01" superano la validazione, ma nei nostri test ogni task è fallito. Usa numeri in forma di stringa, ad esempio "1042".

Google-Imagen4 è un altro modello? Nei nostri test, le richieste inviate con "model": "Google-Imagen4" sono andate a buon fine, mentre il payload del task riportava "model": "imagen-4.0". Nel nuovo codice usa imagen-4.0.

Prossimi passi

Scegli un prodotto, scrivi per esso i tre modelli di prompt illustrati sopra ed esegui lo script di elaborazione batch su Imagen 4. Se vuoi integrarlo in una pipeline di catalogo, la documentazione dell'API asincrona copre autenticazione e polling.