flux-2 per le immagini di prodotto e-commerce: guida pratica all'API hiapi

TL;DR

• Di cosa si tratta: una guida pratica per generare immagini di prodotto e-commerce con flux-2/text-to-image su hiapi. Ogni immagine in questa pagina è stata generata dal prompt esatto stampato immediatamente sopra — nessuna demo presa in prestito — così puoi riprodurre ciascuna di esse.
• Perché flux-2 è adatto alle immagini di prodotto: punta su aderenza al prompt e alta fedeltà, esattamente ciò che serve al lavoro di catalogo — numero esatto di articoli, colori specifici, sfondi puliti e uniformi e etichette vuote (senza testo) vengono rispettati rigorosamente.
• Fatti sul modello (verificati sull'API): flux-2 gira su un endpoint asincrono di task (/v1/tasks). input.resolution usa la forma in megapixel — 0.5 MP, 1 MP, 2 MP o 4 MP — non 1K/2K. aspect_ratio è opzionale e accetta valori come 1:1, 3:2, 16:9.
• Prezzi (per immagine): 0.5 MP costa $0.0375, 1 MP $0.05, 2 MP $0.075, 4 MP $0.125. Per i prezzi in tempo reale consulta la pagina prezzi.
• Come eseguirlo: invia una richiesta POST all'API dei task, esegui il polling finché lo stato non è success, poi scarica l'immagine da output[0].url (l'URL scade — salva subito i byte). Lo script completo da copiare e incollare è alla fine, con un ciclo batch.

Perché flux-2 è adatto alla fotografia di prodotto

La maggior parte dei modelli text-to-image sa disegnare una bella tazza. Il problema nell'e-commerce non è la "bellezza", ma la precisione. Una scheda prodotto richiede il colore corretto, il numero corretto di articoli, uno sfondo pulito con spazio per sovrapporre il tuo testo e etichette lasciate vuote per inserire in seguito il copy reale. Quando il modello si prende libertà — disegna una bottiglia in più, inventa il testo dell'etichetta, colora lo sfondo bianco — l'immagine non è pubblicabile.

flux-2 è etichettato come aderenza al prompt e alta fedeltà, il che in pratica significa che tende a eseguire il prompt alla lettera. È proprio questo il punto chiave per le immagini di catalogo: tu scrivi i vincoli, il modello li rispetta invece di "interpretarli creativamente". Le ricette qui sotto sono costruite proprio su questo — ognuna si basa su un vincolo specifico (quantità, colore, layout) così puoi vedere di persona l'aderenza.

Come leggere queste ricette

Ogni ricetta contiene tre parti: una riga di obiettivo, il prompt esatto (da copiare così com'è) e l'immagine che genera. Ogni prompt è stato scritto da me e eseguito su flux-2 tramite l'API dei task reale. Alcune abitudini che funzionano sempre bene con questo modello:

• Specifica lo sfondo. "Sfondo da studio grigio chiaro senza giunzioni" è meglio che lasciare al caso, e rende l'immagine direttamente utilizzabile nella pagina di dettaglio prodotto (PDP).
• Scrivi "nessun testo, nessun logo" quando vuoi etichette vuote. flux-2 lo rispetta, il che significa che puoi aggiungere il marchio reale a valle.
• Dagli vincoli contabili e verificabili. "Esattamente tre bottiglie", "ambra a sinistra, trasparente al centro, ciano a destra" — le istruzioni specifiche sono il punto in cui l'aderenza fa la differenza.
• Riserva spazio negativo nel prompt ("ampio spazio vuoto in alto per il titolo"), soprattutto quando l'immagine sarà posta sotto del testo sovrapposto.

Ricetta 1 — Sfondo bianco pulito

Obiettivo: l'immagine di listino più basilare — un prodotto, sfondo senza giunzioni, margini uniformi, pronta da inserire nella pagina prodotto.

A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, empty and unbranded. Soft even top-light with one subtle rim highlight down the left edge, a soft grounded contact shadow beneath. Studio e-commerce packshot, perfectly centered, wide even margins on all sides, photoreal, high detail, no text, no logo.

Margini e centratura derivano direttamente dal prompt — richiederli esplicitamente è ciò che rende il ritaglio utilizzabile nella griglia del listino.

Ricetta 2 — Test di aderenza al prompt

Obiettivo: dimostrare che il modello segue istruzioni precise e contabili — è proprio per questo che si sceglie flux-2 per il lavoro sui prodotti.

Product photo of exactly three glass spray bottles standing in a row on a white acrylic surface: the left bottle filled with pale amber liquid, the middle bottle filled with clear liquid, the right bottle filled with soft teal liquid. All three have matte-black fine-mist pump tops and blank labels with no writing. Even frontal studio light, soft reflections on the acrylic, seamless white background. Photoreal commercial product photography, sharp focus, no text anywhere in the image.

Contali: tre flaconi, non quattro. Da sinistra a destra il liquido è ambra, trasparente, ciano — nell'ordine corretto. Le pompe sono nero opaco. Le etichette sono vuote, così potrai aggiungere il copy reale in seguito. Questo è il guadagno — tu specifichi, lui rispetta, l'immagine è subito utilizzabile.

Ricetta 3 — Lifestyle/scena

Obiettivo: collocare il prodotto in una scena senza farlo sparire — l'immagine "in uso" da affiancare alla foto su sfondo bianco nella scheda prodotto.

Lifestyle e-commerce shot of a tan leather crossbody bag resting on a pale oak cafe table beside a folded newspaper and a cup of espresso, soft morning window light from the left, warm out-of-focus cafe interior in the background with creamy bokeh. The bag is the clear hero, sharp and well-lit, staged naturally but uncluttered. Photoreal, editorial product-in-use photography, warm neutral palette, shallow depth of field, no visible brand marks or text.

Indicare il protagonista ("la borsa è chiaramente l'eroe, nitida") e spingere tutto il resto nel fuori fuoco mantiene il prodotto riconoscibile pur raccontando una storia — è proprio l'equilibrio che serve a un'immagine lifestyle.

Ricetta 4 — Set di angolazioni multiple per PDP

Obiettivo: un set di angolazioni per la pagina di dettaglio prodotto — più viste coerenti dello stesso articolo, con illuminazione e proporzioni corrispondenti.

A clean product-detail-page angle set of one pair of low-top canvas sneakers in off-white, shown as three separate views arranged left to right on a seamless light-grey background: a straight side profile, a three-quarter front angle, and a top-down overhead view. Consistent soft studio lighting and identical scale across all three, even spacing, soft contact shadows. Catalog-grade e-commerce photography, photoreal, crisp, unbranded, no text or labels.

Chiedere "illuminazione coerente e scala identica per le tre viste" è ciò che fa sembrare il set lo stesso prodotto, invece di tre render slegati. Non sostituisce una vera attrezzatura per riprese a 360 gradi, ma è un modo rapido per impostare il layout di una PDP prima del servizio fotografico vero.

Eseguire flux-2 sull'API dei task

flux-2 usa il protocollo asincrono dei task di hiapi — crei un task, ne fai il polling, poi scarichi il risultato. L'unica cosa da azzeccare è: resolution è in forma di megapixel. Invia "1 MP", non "1K", altrimenti l'API restituisce 400 dicendoti che il valore deve essere uno tra 0.5 MP / 1 MP / 2 MP / 4 MP.

1. Crea il task

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
      "aspect_ratio": "1:1",
      "resolution": "1 MP"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

2. Esegui il polling fino al completamento, poi scarica

import os, time, requests

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}


def generate(prompt, aspect_ratio="1:1", resolution="1 MP"):
    # create
    r = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/text-to-image",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
    }).json()
    task_id = r["data"]["taskId"]

    # poll (a single image usually lands well under two minutes)
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            # output[0].url is a temporary link — download the bytes now
            url = task["output"][0]["url"]
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)


img = generate("A single matte-white ceramic coffee mug on a seamless light-grey background, photoreal e-commerce packshot, no text")
open("mug.jpg", "wb").write(img)

L'URL in output[0].url contiene un timestamp expireAt — è un link a breve scadenza. Scarica subito i byte e caricali sul tuo storage; non inserirlo come hotlink in un listino prodotto online.

Generazione batch dell'intero catalogo

Per un negozio reale non fai una sola immagine — ne fai una per ogni SKU. Mantieni una lista di prompt, riutilizza la funzione generate() qui sopra e salva ogni risultato con il nome del suo SKU:

catalog = {
    "SKU-1001": "A single matte-white ceramic coffee mug on a seamless light-grey studio background, three-quarter angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
    "SKU-1002": "A tan leather crossbody bag on a seamless light-grey studio background, front-on, soft studio light, grounded contact shadow, photoreal packshot, no visible brand marks",
    "SKU-1003": "A pair of off-white low-top canvas sneakers, side profile, seamless light-grey background, crisp catalog lighting, photoreal, unbranded, no text",
}

for sku, prompt in catalog.items():
    img = generate(prompt, aspect_ratio="1:1", resolution="1 MP")
    open(f"{sku}.jpg", "wb").write(img)
    print(f"{sku} done")

Prima di ampliare la scala, alcune cose da sapere:

• La risoluzione determina il costo. A 1 MP costa $0.05 per immagine; passa a 2 MP ($0.075) o 4 MP ($0.125) solo per le immagini flagship in cui il dettaglio extra vale la spesa. Un catalogo di 200 SKU a 1 MP costa circa $10. Consulta la pagina prezzi per i numeri aggiornati prima di preventivare.
• Esegui i task in concorrenza. Ogni SKU è un task indipendente — crea più task e fanne il polling in parallelo invece che uno alla volta: i batch grandi si completano in un tempo reale molto breve.
• Mantieni coerente la clausola di "stile". Nota la coda condivisa in ogni prompt qui sopra ("sfondo da studio grigio chiaro senza giunzioni... scatto fotorealistico, nessun testo"). Blocca quella formulazione per far sembrare un lotto di immagini un catalogo, non un insieme eterogeneo.

Punti chiave

• Il punto di forza di flux-2 nel lavoro sui prodotti è eseguire rigorosamente ciò che chiedi alla lettera — quantità esatte, colori esatti, etichette vuote — quindi scrivi esplicitamente i vincoli e lascialo aderire.
• Specifica sempre lo sfondo nel prompt e riserva spazio negativo; questo rende i render direttamente utilizzabili nel listino prodotto.
• Sull'API dei task, invia resolution in megapixel (1 MP), esegui il polling di /v1/tasks/{id} fino a success e scarica prima che output[0].url scada.
• Il prezzo cresce con la risoluzione — usa 1 MP per i batch di catalogo e lascia 2 MP/4 MP alle immagini flagship.

Pronto a provarlo? Ottieni una chiave, punta model su flux-2/text-to-image e controlla le tariffe in tempo reale sulla pagina prezzi prima di generare il catalogo in batch.