Blog

Guida all'uso

Generare immagini di prodotto per l'e-commerce con flux-3 tramite l'API HiAPI

Modelli di prompt, controllo di sfondo e illuminazione, e una richiesta di generazione di foto prodotto eseguibile

Nov 12, 2026
Copertina in stile incisione a tratteggio: linee parallele color rame su blu notte formano cornici di prodotto astratte e una pipeline a gradini.
In questa pagina

Perché flux-3 è adatto alle foto di prodotto per l'e-commerce

Le pipeline di catalogo prodotti falliscono per ragioni spesso banali: la coerenza. Una pagina prodotto non è una singola immagine principale, ma decine di immagini che attraversano più SKU, più angolazioni e aggiornamenti stagionali, e che devono tutte sembrare scattate nello stesso pomeriggio nello stesso studio fotografico. Affidare ogni immagine a un fotografo è lento e costoso; affidare ogni immagine a un generatore di immagini qualsiasi di solito produce un insieme di immagini ciascuna plausibile ma goffa se messa accanto alle altre.

È proprio qui che flux-3 è utile. È un modello di generazione di immagini fornito tramite l'API HiAPI, il che significa che la tua pipeline di prodotto può trattare la creazione di immagini come l'ennesima chiamata HTTP: invii il prompt più i parametri del prodotto, ricevi un'immagine, la memorizzi e passi allo SKU successivo. Nessun SDK specifico del fornitore, nessun account separato per ogni modello, nessun codice collante da scrivere per ogni provider.

Ciò che conta particolarmente per l'e-commerce è che flux-3 risponde in modo prevedibile alla struttura del prompt. La fotografia di prodotto è una scena altamente vincolata: un soggetto, centrato o deliberatamente inquadrato, uno sfondo pulito e un'illuminazione in stile studio. Questi vincoli sono esattamente ciò che puoi esprimere a parole e, una volta diventati testo, diventano variabili di un modello anziché decisioni creative. È questa la differenza tra «chiedere un'immagine al modello» e avere un vero e proprio passo di generazione all'interno di un'attività di catalogo.

Il flusso di lavoro pratico di questa guida è: definire una struttura di prompt riutilizzabile, ritoccare la formulazione di sfondo e illuminazione finché la base non appare corretta, quindi sostituire il blocco del soggetto per ogni prodotto. Tutto il resto resta invariato, ed è proprio questo che ti garantisce coerenza visiva su un'intera linea di prodotti.

Cosa ti serve prima di iniziare

  • Una chiave API HiAPI e l'attuale identificatore del modello flux-3 ottenuto dall'elenco dei modelli della piattaforma.
  • Dati di prodotto in forma strutturata: nome, materiale, colore, forma e qualsiasi dettaglio saliente che desideri far rendere al modello.
  • Un luogo in cui conservare il prompt di base e gli output generati, così da poter confrontare le versioni in seguito.
Un solo prodotto, reso in modo coerente su nove sfondi controllati: è questa la promessa di flux-3 per la coerenza del catalogo.

La struttura di un prompt per foto di prodotto con flux-3

Un prompt che funziona per un solo prodotto serve a poco. Un prompt che puoi compilare è utile. Il modo per ottenerlo è scomporre la descrizione in blocchi fissi, ciascuno corrispondente a una variabile nel tuo codice.

I cinque blocchi

  • Soggetto. Che cos'è l'oggetto, descritto con nomi concreti. «Una tazza da caffè in ceramica opaca» è meglio di «una bella tazza». Aggiungi indizi di scala dove contano («slanciata», «a bocca larga»).
  • Materiale e superficie. Finitura e texture: alluminio spazzolato, ceramica smaltata, cotone intrecciato, vetro smerigliato. È da qui che provengono i riflessi del modello, quindi sii esplicito.
  • Sfondo. Lo sfondo e il piano d'appoggio su cui si trova il prodotto: carta senza giunte, ardesia, gradiente morbido, fondale bianco senza giunte. Mantieni questo blocco volutamente breve e noioso: è impalcatura, non uno spazio creativo.
  • Illuminazione. Direzione, qualità e contrasto: luce principale morbida da sinistra, grande sorgente diffusa, riempimento delicato, ombra sottile sotto l'oggetto. Questo blocco determina gran parte dell'effetto «studio» ed è quello che ritoccherai di più.
  • Inquadratura della fotocamera. Come viene composta l'immagine: foto prodotto centrata, altezza occhi, angolazione a tre quarti, taglio stretto, ampio spazio negativo sopra.

Trasformare i blocchi in un modello

Questi blocchi vengono assemblati in fase di esecuzione in un'unica stringa, sostituendo solo il soggetto (e occasionalmente il materiale) per ogni SKU:

product photo of {subject}, {material}, {background}, {lighting}, {framing}

Un esempio compilato:

product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above

Due regole mantengono stabile il modello. Primo, mantieni fisso l'ordine dei blocchi: anche con un testo identico, riordinare i blocchi cambia l'enfasi. Secondo, mantieni i blocchi fissi come la stessa identica stringa tra gli SKU, invece di riscriverli ogni volta; una lieve deriva nella formulazione è la causa più comune di sfondi e illuminazioni incoerenti in un catalogo.

Dove la creatività non deve entrare

Evita un linguaggio editoriale nei blocchi fissi: niente aggettivi emotivi, niente orpelli di styling, niente riferimenti a scene. Lascia ogni variazione a campagne marketing deliberate e mantieni pulito il modello del catalogo. Un modello che si legge come una specifica tecnica produce immagini che sembrano una specifica tecnica: ed è esattamente ciò di cui ha bisogno una scheda prodotto.

Ogni blocco del prompt — soggetto, materiale, sfondo, illuminazione, inquadratura — è una tessera intercambiabile che puoi riordinare e riutilizzare.

Controllare sfondo e illuminazione

Sfondo e illuminazione sono i due blocchi che determinano se un insieme di immagini si legge come un catalogo coerente. Entrambi rispondono bene a una formulazione concreta e fisica.

Sfondo: punta alla noia

Descrivi lo sfondo come un allestimento fisico, non come un'estetica. «Fondale in carta grigio chiaro senza giunte» e «fondale bianco infinito» sono affidabili perché descrivono un allestimento da studio noto. Parole come «minimalista» o «estetico» sono vaghe e spesso fanno filtrare elementi della scena.

Leve utili:

  • Tipo di superficie: carta senza giunte, vinile opaco, ardesia naturale, legno chiaro.
  • Colore e tonalità: grigio chiaro, bianco sporco, sabbia caldo — mantieni la luminosità da media a chiara, così i bordi del prodotto restano leggibili.
  • Continuità: «senza giunte» o «infinito» dice al modello che vuoi che sfondo e piano si fondano, eliminando quella linea d'orizzonte difficile da ripulire in seguito.
  • Vuoto: se i primi tentativi introducono oggetti estranei, vale la pena scrivere esplicitamente «sfondo vuoto, nessun oggetto di scena».

Se ti serve un PNG con sfondo trasparente per il marketplace, genera prima su uno sfondo pulito e uniforme, poi esegui il ritaglio in post-produzione. Chiedere al modello di immagini un vero canale alfa non è una strada affidabile.

Illuminazione: prima la direzione, poi la qualità

La formulazione dell'illuminazione si divide nettamente in due decisioni. La direzione determina dove cadono riflessi e ombre; la qualità determina quanto sono morbidi i bordi di quei riflessi.

  • Direzione: «luce principale dall'alto a sinistra», «luce principale morbida frontale», «luce da destra con riempimento delicato a sinistra». Scegline una e mantienila su tutta la linea di prodotti.
  • Qualità: «grande sorgente diffusa», «ombre morbide», «illuminazione uniforme». La luce diffusa morbida è un default sicuro per le foto di prodotto, perché non sovraespone i materiali lucidi.
  • Ombra di contatto: «una morbida ombra di contatto sotto il prodotto» fa poggiare l'oggetto; senza di essa il prodotto sembra fluttuare.
  • Contrasto: «basso contrasto, luminoso e uniforme» è adatto ai marketplace su fondo bianco; un contrasto direzionale leggermente maggiore è adatto ai ritagli lifestyle premium.

Mantenere coerente una linea di prodotti

La coerenza è più una questione di gestione delle versioni che di prompt. Conserva i blocchi di sfondo e illuminazione come preset con un nome (ad esempio un preset «studio bianco» e uno «ardesia») e fai riferimento al preset per nome in ogni attività di generazione, invece di incollare il testo per ogni SKU. Quando modifichi un preset, lo modifichi una volta sola, e il lotto successivo eredita la modifica in modo intenzionale, anziché andare alla deriva.

Quando un risultato non è quello giusto, cambia un solo blocco alla volta e rigenera lo stesso prodotto. Cambiare sfondo e illuminazione insieme non ti permette di capire quale formulazione abbia fatto la differenza.

Frecce direzionali della luce e campioni di sfondo: come la formulazione del prompt si traduce in un aspetto coerente della linea di prodotti.

Una richiesta HiAPI a flux-3 realmente eseguibile

Il passo di generazione è una chiamata API. Il percorso esatto dell'endpoint, l'identificatore del modello e i campi della richiesta sono documentati sulla piattaforma e vanno presi da lì, perché possono evolvere; la forma riportata di seguito è lo schema da collegare al tuo script.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

presets = {
    "white_studio": {
        "background": "on a pure white infinity sweep, no props, empty backdrop",
        "lighting": "soft diffused key light from the upper left, even fill, "
                    "soft contact shadow beneath the product, low contrast",
        "framing": "centered eye-level product shot, generous negative space",
    }
}

def build_prompt(product, preset_name="white_studio"):
    p = presets[preset_name]
    return (
        f"product photo of {product['subject']}, {product['material']}, "
        f"{p['background']}, {p['lighting']}, {p['framing']}"
    )

def generate(product, preset_name="white_studio"):
    payload = {
        "model": "flux-3",           # confirm the current identifier in the model list
        "prompt": build_prompt(product, preset_name),
    }
    response = requests.post(
        "https://api.hiapi.ai/v1/images/generations",  # see docs for exact path
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

product = {
    "subject": "a matte ceramic coffee mug",
    "material": "glazed stoneware with visible clay texture",
}

result = generate(product)
print(result)

Collegarlo all'elaborazione in batch

Alcune abitudini ti permettono di eseguirlo in sicurezza su un intero catalogo, anziché su un singolo prodotto:

  • Risolvi ogni valore da variabili d'ambiente. Tieni le chiavi lontane dal codice sorgente e dai log.
  • Considera la risposta non attendibile. Leggi il riferimento o il payload dell'immagine restituita dai campi documentati, poi scaricala e salvala nel tuo bucket di archiviazione. Non fare affidamento su URL temporanei che durino più a lungo del task.
  • Registra la stringa esatta del prompt insieme a ogni output. Conservala con i metadati dell'immagine. Quando in futuro qualcuno chiederà perché l'immagine dello SKU 1234 appare diversa, la risposta deve trovarsi nel tuo database, non nella memoria di qualcuno.
  • Usa tentativi con backoff per i guasti transitori, e limita la concorrenza, così un lotto grande non innesca limiti di frequenza.
  • Mantieni le richieste idempotenti per SKU e versione del prompt, così una nuova esecuzione sovrascrive lo stesso slot di output, invece di spargere duplicati.

Dall'iterazione sul modello alla pipeline di produzione

Il primo prompt verificato è una base di partenza, non un asset finito. Rendere tutto produttivo significa trasformarlo in qualcosa che la tua pipeline possa riprodurre e verificare.

Passo 1: blocca la baseline su un piccolo campione

Genera da cinque a dieci prodotti di diverse categorie di materiale: uno lucido, uno opaco, uno in tessuto, uno in metallo, uno trasparente. Questi metteranno alla prova il blocco dell'illuminazione in modi diversi. Se il modello regge su questo campione, hai una baseline; se il prodotto lucido si sovraespone o il tessuto appare piatto, ritocca quel blocco ora, non dopo aver eseguito tutto il catalogo.

Passo 2: assegna un nome ai preset e versiona

Dai al preset un identificatore di versione esplicito e tratta le modifiche come nuove versioni, non come semplici edit. Uno schema semplice come white_studio_v1 → white_studio_v2 ti permette di rigenerare un lotto con il vecchio preset e confrontare, e ti consente anche di tornare indietro se un «piccolo miglioramento» si rivela una regressione su metà dei tuoi SKU.

Passo 3: conserva i prompt dove la pipeline può leggerli

Mantieni due livelli: le definizioni condivise dei preset (sfondo, illuminazione, inquadratura, versione) in un unico posto, e i campi soggetto e materiale di ogni SKU nel tuo database di prodotto. Il codice di generazione poi combina i due. Ciò significa che le modifiche ai preset si propagano a ogni attività futura, mentre i dati del soggetto restano di proprietà del team del catalogo.

Passo 4: confronta gli output in modo sistematico

La revisione affiancata non è scalabile oltre qualche decina di SKU. Segnali più economici:

  • Revisione tramite foglio di contatto: monta un lotto in un'unica griglia e cerca le anomalie. Sfondi che derivano e inquadrature spostate saltano subito all'occhio alla dimensione di una miniatura.
  • Campionamento dei bordi per verificare lo sfondo: campiona il colore dei pixel vicino ai bordi dell'immagine e segnala i risultati in cui gli angoli si discostano dalla tonalità attesa dal preset. Questo intercetta il guasto più comune — uno sfondo che cambia colore di nascosto — senza bisogno dell'occhio umano.
  • Controllo della posizione nella cornice: se il prodotto deve essere centrato con spazio negativo sopra, misura dove si trova la massa del soggetto in ogni immagine e segnala le anomalie.

Tutto ciò che viene segnalato entra nella coda di revisione; tutto il resto viene pubblicato automaticamente.

Passo 5: rigenera in modo intenzionale

Una volta stabilizzata la baseline, un nuovo SKU è un problema di dati, non di prompt: aggiungi i campi soggetto e materiale, accoda il task e lascia che l'automazione se ne occupi. Riserva le esecuzioni di rigenerazione a modifiche intenzionali — sfondi stagionali, nuove varianti di illuminazione — e in quel caso incrementa la versione del preset.

Trappole comuni e come evitarle

La maggior parte dei fallimenti nella generazione di immagini di prodotto riguarda sempre gli stessi pochi problemi, ciascuno con una soluzione sul lato del prompt o sul lato della pipeline.

Deriva dello sfondo nei lotti

La lamentela più comune: le immagini sono coerenti se guardate singolarmente, ma differiscono tra gli SKU. Quasi sempre è una deriva nella formulazione: qualcuno ha riscritto il blocco dello sfondo, oppure il modello ha inserito al suo interno attributi del prodotto. Soluzione: tratta sfondo e illuminazione come stringhe fisse provenienti da un'unica fonte di preset, e nel codice verifica che il prompt assemblato contenga letteralmente il testo del preset.

Oggetti di scena e elementi di scena indesiderati

Al modello piace aggiungere sfondo: un rametto, un pezzo di stoffa piegata, un'ombra che sembra il bordo di un tavolo. Dichiara esplicitamente il vuoto («sfondo vuoto, nessun oggetto di scena») e mantieni il linguaggio della scena il più possibile fisico e circoscritto allo studio. Se il problema persiste, semplifica la descrizione del soggetto: gli aggettivi decorativi nel blocco del soggetto tendono a richiamare decorazioni corrispondenti nella scena.

Prodotti fluttuanti

Senza un'ombra di contatto l'oggetto sembra incollato allo sfondo. Includi «una morbida ombra di contatto sotto il prodotto» nel blocco dell'illuminazione e specifica che il prodotto poggia su una superficie anziché sospeso.

Inquadratura incoerente

Mescolare ritagli diversi rovina una pagina di categoria. Fissa il blocco dell'inquadratura in un'unica frase e non lasciarlo variare; se ti servono più formati, genera la stessa composizione e ritaglia in post-produzione, invece di scrivere prompt per ogni proporzione.

Prompt eccessivamente specificati

Prompt troppo lunghi che descrivono la storia, il marchio e il racconto del prodotto producono spesso immagini editoriali anziché da catalogo. Il modello dovrebbe leggersi come una lista delle inquadrature. Quando un risultato sembra sbagliato, la soluzione di solito è togliere parole, non aggiungerne.

Trattare un fallimento di generazione come un bug del codice

Un singolo risultato scadente non è un segnale per riscrivere la pipeline. Riproducilo con la stringa esatta del prompt memorizzata, cambia un blocco, rigenera e trai le conclusioni solo dopo. Registrare il prompt insieme a ogni output è proprio ciò che lo rende possibile, ed è l'abitudine più economica da adottare per prima.

Inizia con un preset, un lotto campione e il prompt memorizzato per ogni immagine; amplia solo dopo che la baseline regge su tutti i tipi di materiale.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API