FLUX 1.1 Pro per immagini prodotto e-commerce: guida all'API hiapi

Se vendi online, conosci già i conti: una pagina di dettaglio prodotto richiede un'immagine su sfondo bianco, un'immagine in contesto e, meglio ancora, una serie di scatti da più angolazioni — per ogni SKU, per ogni variante colore. Un giorno di shooting in studio copre dieci prodotti; un'API di immagini ne copre mille.

flux-1.1-pro (FLUX.1.1 [pro] di Black Forest Labs) è il modello di punta per il fotorealismo su hiapi: rende materiali credibili — metallo spazzolato, vetro, tessuto, bokeh morbido — a un costo fisso di $0.05 per immagine. Questa guida è una ricetta e-commerce pronta all'uso: ogni immagine qui sotto è stata generata con il prompt stampato testualmente sopra di essa, tramite le stesse chiamate /v1/tasks che puoi copiare e incollare, e abbiamo documentato gli intervalli di parametri reali — inclusi quelli che sembrano dover esistere ma che restituiscono 400 se inviati.

L'API in 60 secondi

Su hiapi, flux-1.1-pro gira su un endpoint a task asincrono. Crei il task, lo interroghi e scarichi il risultato:

# 1. Create the task
curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "input": {
      "prompt": "Studio packshot of an unbranded stainless steel wristwatch...",
      "aspect_ratio": "1:1",
      "output_format": "jpg",
      "seed": 6607
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KWK3JG..."},"message":"success"}

# 2. Poll until status is "success" (typically 10–40s for flux-1.1-pro)
curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWK3JG... \
  -H "Authorization: Bearer $HIAPI_API_KEY"

# 3. Download output[0].url — it carries an expireAt timestamp,
#    so save the file to your own storage immediately.

Prima di entrare nel vivo, due note operative:

• Gli URL di output sono temporanei. Scarica e ricarica subito dopo il successo del task — vedi cosa succede quando l'URL di output di hiapi scade.
• Se un task resta in stato processing più del previsto, non reinviarlo alla cieca; ecco una guida diagnostica per task bloccati o in timeout.

Gli intervalli di parametri reali (e i 400 che ottieni tirando a indovinare)

Se hai usato modelli FLUX su altre piattaforme, la memoria muscolare ti spingerà a regolare steps e guidance. Ma nello schema dei task di hiapi per flux-1.1-pro, questi campi non esistono — l'API valida rigorosamente l'input e rifiuta le proprietà sconosciute:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'steps', 'guidance' not allowed"
}

Non è un bug; FLUX 1.1 [pro] è offerto come endpoint gestito e i meccanismi interni di campionamento sono fissati dal provider. Ecco cosa puoi inviare, verificato sullo schema in produzione:

Campo	Tipo	Valori / intervalli accettati
prompt	string	obbligatorio
aspect_ratio	string	1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, custom
width, height	integer	256–1440 px (in alternativa all'aspect ratio, o in abbinamento all'aspect ratio custom)
seed	integer	qualsiasi intero — fissa la composizione per la riproducibilità
output_format	string	jpg, png, webp
prompt_upsampling	boolean	fa riscrivere/estendere il prompt dal backend
safety_tolerance	integer	0–6

Default pratici per le immagini prodotto: output_format: "jpg", un aspect_ratio esplicito in base al posizionamento (1:1 per le griglie del negozio, 4:5 per feed/lifestyle, 3:2 o 1440×960 per i banner), un seed fisso per ogni famiglia di SKU e prompt_upsampling disattivato — in contesto e-commerce vuoi che il modello segua rigorosamente le tue parole, non che aggiunga dettagli di propria iniziativa.

Ricetta 1 — Packshot pulito su sfondo bianco

L'immagine di base: un prodotto, sfondo continuo, luce principale morbida. Specifica esplicitamente il colore dello sfondo, richiedi il riflesso sul piano e — cosa importante con qualsiasi modello fotorealistico — scrivi sempre "senza marchio, senza logo, senza testo". Quadranti ed etichette sono esattamente dove FLUX può inventare scarabocchi a forma di marchio che poi dovresti ritoccare.

Studio packshot of an unbranded stainless steel wristwatch with a plain deep green dial and brushed metal bracelet, the dial completely clean with simple baton hour markers and no logo, no brand name, no text or numerals anywhere, standing upright on a seamless light grey background, centered composition, soft diffused key light from the upper left, subtle reflection beneath the watch, photorealistic e-commerce product photography

Invialo con aspect_ratio: "1:1", seed: 6607. La resa del metallo spazzolato e il riflesso morbido sul piano sono ciò che paghi con il livello professionale da $0.05 — i modelli economici appiattiscono proprio questi dettagli.

Ricetta 2 — Immagine in contesto

Le griglie del negozio richiedono lo sfondo bianco; le pagine prodotto e i social convertono con la scena. Metti il prodotto in un ambiente, lascia l'etichetta bianca e usa la profondità di campo ridotta per trasmettere un senso di qualità. 4:5 corrisponde al ritaglio del feed.

A lit soy candle in a clear glass jar with a plain blank kraft-paper label, on a rustic oak nightstand next to a stack of two linen-bound books, warm evening window light, softly blurred bedroom background, cozy lifestyle product photography for an online store, photorealistic

Inviala con aspect_ratio: "4:5", seed: 7301. Nota che l'etichetta bianca è rimasta tale — è la tela su cui sovrapporre poi la grafica del tuo marchio.

Ricetta 3 — Varianti colore con seed fisso

È il trucco che fa risparmiare più soldi nella creazione di cataloghi. Il seed fissa l'inizializzazione del rumore, quindi se mantieni identici seed e struttura del prompt e cambi solo la parola del colore, ottieni la stessa composizione nella nuova variante colore — senza nuovi scatti, senza flusso img2img.

Entrambe le immagini qui sotto usano seed: 5150, aspect_ratio: "1:1", e i prompt differiscono esattamente per due parole (navy blue → coral pink):

A single insulated stainless steel water bottle in matte navy blue, standing on a round travertine stone slab against a soft warm beige studio background, centered, soft diffused lighting, minimalist e-commerce product photo, photorealistic

Stessa sagoma della borraccia, stessa lastra, stessa composizione, ma SKU diverso. Ecco come un prompt con seed fisso sostituisce una giornata di shooting di varianti.

Batch: renderizza l'intero catalogo per SKU

Ecco il pattern che abbiamo effettivamente eseguito: invio, polling, download, retry. Un'esecuzione in produzione ha rivelato un aspetto da pianificare in anticipo: i task flux-1.1-pro falliscono occasionalmente con un generico {"code": "TASK_FAILED"} — è transitorio, e reinviando lo stesso input di solito va a buon fine. Prevedi fino a 3 tentativi per immagine (paghi solo per le immagini renderizzate con successo).

import json, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_HIAPI_KEY",
           "Content-Type": "application/json"}

CATALOG = [
    {"sku": "bottle-navy",  "colour": "matte navy blue"},
    {"sku": "bottle-coral", "colour": "matte coral pink"},
    {"sku": "bottle-sage",  "colour": "matte sage green"},
]
TEMPLATE = ("A single insulated stainless steel water bottle in {colour}, "
            "standing on a round travertine stone slab against a soft warm "
            "beige studio background, centered, soft diffused lighting, "
            "minimalist e-commerce product photo, photorealistic")

def render(prompt, seed, retries=3):
    for attempt in range(retries):
        task = requests.post(API, headers=HEADERS, json={
            "model": "flux-1.1-pro",
            "input": {"prompt": prompt, "aspect_ratio": "1:1",
                      "output_format": "jpg", "seed": seed},
        }).json()
        task_id = task["data"]["taskId"]
        while True:
            state = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
            if state["status"] == "success":
                return requests.get(state["output"][0]["url"]).content
            if state["status"] == "fail":          # transient TASK_FAILED happens;
                break                              # resubmit with the same input
            time.sleep(5)
    raise RuntimeError(f"gave up after {retries} attempts")

for item in CATALOG:
    img = render(TEMPLATE.format(colour=item["colour"]), seed=5150)
    with open(f"{item['sku']}.jpg", "wb") as f:
        f.write(img)                               # re-host immediately; task URLs expire
    print(item["sku"], "done")

Se devi elaborare centinaia di SKU, regola il ritmo degli invii — limiti di rate delle API di generazione immagini spiegati illustra il comportamento dei limiti e un livello di concorrenza ragionevole.

Prezzi e quando scegliere flux-1.1-pro

Verificato sulla pagina prezzi di hiapi:

Modello	Prezzo per immagine	Caso d'uso
flux-schnell/text-to-image	$0.005	Bozze, composizioni di layout, miniature in grandi volumi
flux-1.1-pro	$0.05 fissi	Packshot fotorealistici e immagini in contesto, fino a 1440px a qualsiasi risoluzione
flux-2/text-to-image	$0.0375–$0.125 (per MP)	Massima aderenza al prompt, testo leggibile nell'immagine

Il prezzo fisso è un vantaggio discreto: un banner hero 1440×960 e una miniatura 512×512 costano entrambi $0.05, mentre flux-2 fattura a megapixel. Se il tuo carico di lavoro è "immagini prodotto fotorealistiche, formati misti", flux-1.1-pro è la scelta predefinita a costo prevedibile; se ti servono conteggi precisi degli oggetti o testo stampato leggibile nell'immagine, passa a flux-2 — che abbiamo testato qui con la stessa ricetta e-commerce.

Una PDP con cinque immagini (principale, sfondo bianco, lifestyle, due varianti colore) costa $0.25 per prodotto. Aggiornare un catalogo di 200 SKU: $50, un pomeriggio, uno script.

Conclusione

flux-1.1-pro su hiapi ti offre immagini prodotto fotorealistiche con un flusso asincrono in due chiamate: un intervallo di parametri rigoroso ma semplice (aspect ratio, dimensioni, seed, formato — senza dover armeggiare con steps/guidance), varianti colore con seed fisso e un prezzo fisso di $0.05 che rende il budget del catalogo estremamente prevedibile. Prendi la tua API key, parti dalla pagina del modello flux-1.1-pro, renderizza il tuo primo packshot con la chiamata curl qui sopra — e avrai un'immagine pronta per la PDP prima che il caffè si raffreddi.