flux-2/image-to-image per le immagini di prodotti e-commerce: guida all'API hiapi

Se hai già discrete foto di prodotto — anche scatti disordinati con sfondo sbagliato o ritaglio impreciso — flux-2/image-to-image può trasformarle in immagini e-commerce pronte per la pubblicazione senza dover rifare il servizio fotografico. È un modello di editing, non di text-to-image: gli dai da 1 a 8 immagini di riferimento più un'istruzione e restituisce una nuova immagine che preserva con precisione forma, colore, materiale e proporzioni del prodotto, cambiando tutto ciò che lo circonda — sfondo, illuminazione, composizione e persino la scena in cui si trova il prodotto.

Abbiamo testato end-to-end due attività e-commerce comuni tramite l'endpoint /v1/tasks di hiapi — sostituzione dello sfondo da studio e composizione in scene lifestyle — e prima di scrivere queste note abbiamo verificato lo schema di input, il comportamento del rapporto d'aspetto e i prezzi reali per immagine confrontandoli con la pagina dei prezzi di hiapi.

• flux-2/image-to-image accetta fino a 8 immagini di riferimento per singola chiamata, quindi la sostituzione dello sfondo (1 immagine) e la composizione in scena (2 o più) usano esattamente lo stesso endpoint.
• aspect_ratio: "auto" segue davvero il rapporto d'aspetto dell'immagine di input: una foto verticale 9:16 di una scarpa da running resta 9:16, a meno che tu non la sovrascriva. Valori espliciti come "1:1" impongono invece quella forma, indipendentemente da ciò che hai in input.
• Il prezzo è a fasce di risoluzione: 1K a $0.035/immagine, 2K a $0.05/immagine — prezzo fisso, senza fatturazione a megapixel.
• È una vera modifica, non una ridipintura: il logo, le cuciture e la trama del materiale del prodotto restano intatti anche dopo il cambio di sfondo/scena.
• Un unico script di batch processing (vedi sotto) basta per elaborare un intero catalogo prodotti con lo stesso prompt di pulizia dello sfondo.

Cosa fa realmente flux-2/image-to-image

Sotto il cofano è un singolo modello sull'interfaccia unificata delle attività di hiapi: non scegli tra uno strumento di "rimozione sfondo" e uno di "composizione", ma scrivi un'istruzione e fornisci le immagini di riferimento corrette per l'attività:

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Remove the background and place the product on a seamless white studio background with a soft contact shadow. Keep the product'"'"'s shape, color and proportions unchanged.",
      "image_urls": ["https://your-cdn.example.com/raw-product-photo.jpg"],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }'

I campi obbligatori sono prompt (stringa), image_urls (array, massimo 8), aspect_ratio (auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 o 2:3) e resolution (1K o 2K). La risposta restituisce un taskId: esegui il polling di GET /v1/tasks/{taskId} finché status non è success, poi scarica subito l'immagine da output[0].url (il link scade, quindi non trattarlo come archiviazione permanente).

La sostituzione dello sfondo richiede una sola immagine di riferimento. Per comporre il prodotto in una scena lifestyle, passane due: prima l'immagine del prodotto, poi la scena di destinazione, e descrivi nel prompt quale oggetto va dove.

Cosa fa realmente il rapporto d'aspetto "auto"

Questa è la parte da testare prima di costruirci una pipeline attorno, perché è facile dare per scontato che il modello restituisca sempre un quadrato fisso o qualche forma predefinita. Non è così.

Questa è una foto verticale di una scarpa da running, eseguita con aspect_ratio: "auto": l'output è 720×1280, corrispondente esattamente al 9:16 dell'immagine di riferimento in input, senza ritagli né riempimenti in un'altra forma. auto significa "segui l'input", non "scegli un valore predefinito".

Stessa immagine sorgente, stesso prompt: l'unico cambiamento è stato impostare esplicitamente aspect_ratio: "1:1". L'output è un quadrato esatto da 1024×1024, con il modello che ricompone per adattarsi invece di limitarsi a ritagliare. Se il tuo catalogo richiede una griglia quadrata coerente per le pagine di listino, forza quel rapporto; se vuoi che ogni immagine conservi la sua composizione nativa, lascia auto.

Due esempi di composizione in scena

La sostituzione dello sfondo è il caso semplice. La tecnica più utile per i contenuti e-commerce è comporre un'immagine pulita del prodotto in una scena lifestyle — per l'immagine principale, per post social o per foto secondarie "abbinamento" — senza servizio fotografico reale.

Qui sono state fornite due immagini di riferimento: una foto del prodotto delle cuffie su fondo neutro e una scena separata di un tavolo di rovere al sole. Il prompt specificava quale oggetto posizionare e dove ("appoggiate naturalmente accanto alla pianta"), e chiedeva al modello di adattarsi alla direzione della luce già presente nella scena e di proiettare un'ombra credibile — proprio il dettaglio che fa sembrare reale la composizione invece che incollata.

Stessa scena di destinazione, prodotto diverso, sempre con aspect_ratio: "auto" (che eredita la composizione quadrata dell'immagine di riferimento della scena). La forma del filtro e il materiale ceramico sono conservati così come nella foto di riferimento originale — solo l'ambiente circostante è cambiato.

Elaborazione in batch di un catalogo prodotti

A $0.035/immagine (risoluzione 1K) — meno di quanto costi allestire e rifotografare un prodotto — usare flux-2/image-to-image su tutto il catalogo è facile da giustificare. Se vuoi prima testare i prompt a basso costo, prima di passare al modello completo su larga scala vale la pena dare un'occhiata al livello più leggero flux-2-klein-4b/image-to-image; i prezzi attuali di entrambi sono sulla pagina dei prezzi di hiapi.

Una volta messo a punto il prompt per un prodotto, eseguirlo su tutto il catalogo è solo un ciclo sulla stessa richiesta. Questo esempio scorre un set di foto prodotto grezze, esegue la stessa istruzione di pulizia dello sfondo su ciascuna e stampa l'URL di hosting del risultato:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

BACKGROUND_PROMPT = (
    "Remove the existing background and place the product on a seamless pure white "
    "studio background with a soft, realistic contact shadow and even diffused catalog "
    "lighting. Keep the product's exact shape, color, material and proportions unchanged."
)


def edit_product_image(prompt, image_urls, aspect_ratio="auto", resolution="1K"):
    payload = {
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,
        },
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        time.sleep(3)
        status = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        state = status["data"]["status"]
        if state == "success":
            return status["data"]["output"][0]["url"]
        if state == "fail":
            raise RuntimeError(f"task {task_id} failed: {status}")


CATALOG = [
    {"sku": "SNK-001", "image_url": "https://cdn.example.com/raw/snk-001.jpg"},
    {"sku": "HDP-014", "image_url": "https://cdn.example.com/raw/hdp-014.jpg"},
    {"sku": "DRP-022", "image_url": "https://cdn.example.com/raw/drp-022.jpg"},
]

for item in CATALOG:
    out_url = edit_product_image(BACKGROUND_PROMPT, [item["image_url"]])
    print(item["sku"], "->", out_url)

Ogni output[0].url è un link a scadenza: scaricalo e ri-hostalo nel ciclo (il tuo bucket, CDN o qualsiasi servizio che supporta il backend del tuo negozio), invece di salvare il link grezzo. Per una panoramica completa del ciclo attività/polling/download (con gestione degli errori), vedi come usare flux-2/image-to-image tramite l'API hiapi.

Domande frequenti

flux-2/image-to-image modifica il prodotto stesso o solo lo sfondo? Con un prompt adeguato dovrebbe cambiare solo ciò che gli dici di cambiare — sfondo, scena, illuminazione — mantenendo invariati forma, colore e materiale del prodotto rispetto all'immagine di riferimento. Non ogni tentativo è perfetto; prima di pubblicare, confronta l'output con l'immagine sorgente, soprattutto per i testi piccoli o i loghi sulle confezioni.

Quante immagini di riferimento si possono usare per singola chiamata? Fino a 8. La sostituzione dello sfondo ne richiede solo 1. La composizione in scena di solito ne richiede 2 (prodotto + scena di destinazione): più immagini di riferimento sono utili quando vuoi che il modello riproduca un personaggio, un oggetto di scena o un elemento di brand specifico già esistente in un set di foto.

Meglio usare la risoluzione 1K o 2K? 1K ($0.035/immagine) basta per la maggior parte dei cataloghi prodotti e dei listini web — le composizioni delle cuffie e del filtro qui sopra sono state generate a 1K. Per banner hero o per qualsiasi contenuto che verrà ritagliato e ingrandito, scegli 2K ($0.05/immagine).

Qual è la differenza tra flux-2/image-to-image e i livelli Klein? Klein (9b e 4b) scambia parte della fedeltà di editing con un prezzo più basso — ideale per testare i prompt a basso costo prima di eseguire il modello completo su tutto il catalogo. I prezzi attuali sono nella tabella dei prezzi qui sopra.

Posso forzare una dimensione di output invece di lasciarla decidere al modello? Sì: imposta aspect_ratio su un valore esplicito (1:1, 4:3, 16:9, ecc.) invece di auto. Il modello ricompone per adattarsi a quella forma, invece di ritagliare semplicemente l'output con corrispondenza automatica.

Punti chiave

• flux-2/image-to-image modifica foto di prodotto esistenti, non le genera da zero: immagine di riferimento in input, immagine modificata in output, identità del prodotto preservata.
• aspect_ratio: "auto" segue la forma dell'immagine di input; imposta un valore esplicito quando ti serve un rapporto di output coerente in tutta la griglia del catalogo.
• La risoluzione 1K ($0.035/immagine) copre la maggior parte dei casi d'uso e-commerce; 2K ($0.05/immagine) per dimensioni hero o output molto ritagliati.
• Lo stesso endpoint gestisce sia la sostituzione dello sfondo a immagine singola sia la composizione in scena con più immagini — l'unica differenza è quante image_urls passi.
• Il batch processing è solo un normale ciclo attorno al ciclo attività/polling/download, senza bisogno di un endpoint batch separato.

Se sei pronto a usarlo sul tuo catalogo prodotti, la pagina del modello flux-2/image-to-image offre lo schema live e una richiesta di avvio rapido, mentre le ricette di prompt per flux-2/image-to-image raccolgono altri pattern di prompt testati oltre alla sostituzione dello sfondo e alla composizione in scena.