gpt-image-2.5-flare per le immagini prodotto e-commerce: workflow batch basato sull'API hiapi

La fotografia di prodotto è di solito la fase più lenta della pubblicazione di un catalogo: ogni SKU richiede uno scatto in studio, ogni sfondo stagionale una nuova sessione, ogni regola di proporzioni delle diverse piattaforme un ulteriore scatto. gpt-image-2.5-flare su hiapi concentra gran parte di questo lavoro in un unico ID modello: genera immagini prodotto da un prompt testuale e modifica foto esistenti (sostituisce lo sfondo, le colloca in scene di vita, ne adatta le dimensioni per i diversi canali) senza alterare il prodotto stesso. Questa guida lo dimostra attraverso tre workflow reali e output API non modificati, per poi mostrare come applicarlo in batch all'intero catalogo invece di elaborare una sola immagine alla volta.

I prodotti mostrati nelle immagini seguenti (una bottiglia di vetro verde con l'etichetta «MOSS» e un bollitore blu cobalto con l'etichetta «AER») sono oggetti di scena concettuali usati per illustrare questa tecnica, non fotografie reali di clienti — ma ogni immagine è un output reale e non modificato dell'API hiapi, non una simulazione.

Perché la chiave è un solo ID modello

gpt-image-2.5-flare gestisce due tipi di attività diversi in base a ciò che gli passi:

• Omettere image_urls: genera un'immagine solo dal tuo prompt testuale (testo-immagine).
• Aggiungere image_urls: modifica invece la foto fornita (immagine-immagine) — stesso modello, stesso endpoint, stesso prezzo.

Per un catalogo questo conta più di quanto sembri: che tu stia fotografando un prodotto per la prima volta o riutilizzando foto esistenti, non devi saltare tra due ID modello o due piani tariffari. Altri due dettagli lo rendono particolarmente adatto all'elaborazione in batch:

• Livelli di qualità anziché un costo fisso unico. Puoi scegliere low / medium / high / xhigh / max per singola richiesta, così un batch di miniature per 500 SKU e una dozzina di immagini principali per la homepage non devono essere fatturati allo stesso costo unitario.
• Proporzioni flessibili. Ogni richiesta può scegliere 1:1, 4:5, 9:16, 16:9 e altre proporzioni, così la stessa immagine prodotto può essere ritagliata per una griglia quadrata di marketplace, un feed verticale per mobile o un banner ampio senza nuovi scatti.

Ogni chiamata passa attraverso l'API asincrona di task di hiapi:POST /v1/tasks invia il task, poi si interroga GET /v1/tasks/{id} (oppure si usa un callback) finché lo stato non è success. Non esiste una chiamata sincrona che restituisca l'immagine direttamente nella risposta — sia la generazione che la modifica richiedono alcuni secondi.

Passo 1: generare da zero uno scatto in studio pulito

Parti da una foto in studio semplice e ben illuminata: è la base che modificherai nei passaggi successivi.

import os
import time
import requests

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


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" è un valore predefinito ragionevole per un primo passaggio — ogni immagine in questo articolo usa lo stesso livello. Passa un singolo SKU a high solo quando il dettaglio aggiuntivo vale il costo (vedi la tabella dei prezzi qui sotto).

Passo 2: ridisegnare lo sfondo senza rigenerare il prodotto

Questo è il workflow che fa davvero risparmiare lavoro sul catalogo: passa lo scatto in studio come image_urls, descrivi solo la modifica che desideri e il prodotto stesso resta identico a livello di pixel — stessa forma della bottiglia, stesso tappo, stessa etichetta — mentre lo sfondo cambia.

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

Lo stesso schema funziona anche per prodotti completamente diversi — qui un bollitore blu cobalto il cui sfondo è stato sostituito con un telo da studio color pesca caldo, generato allo stesso modo:

Questo è il cuore del compito «rinnovo stagionale» o «tema nuovo mercato»: una chiamata di modifica per SKU, il prodotto resta intatto, lo sfondo cambia. Eseguilo 500 volte e avrai rinnovato il tema dell'intero catalogo senza nuovi scatti.

Passo 3: collocare il prodotto in una scena di vita

Gli scatti in studio vanno bene per le griglie dei marketplace; le scene di vita vendono il prodotto su landing page o in pubblicità. Stesso schema di modifica, prompt più ambizioso — il modello inserisce il prodotto esatto in una scena realistica plausibile, non si limita a cambiare il colore dello sfondo.

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

Mantieni un linguaggio vincolante in ogni prompt di modifica («keep the original ... completely unchanged») — è proprio ciò che impedisce al modello di far variare il prodotto mentre cambia tutto ciò che lo circonda.

Automazione batch per un catalogo completo

Una singola chiamata di modifica è utile; su scala di catalogo il valore sta nell'eseguire lo stesso schema su ogni SKU in modo non presidiato. Ecco la struttura che funziona in produzione:

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

Quando si elaborano più di poche immagini, questi punti contano:

• Chiave di idempotenza per riga. Invia un header Idempotency-Key diverso per ogni SKU/variante, così un nuovo tentativo dopo un timeout non crea — e non fattura due volte — un task duplicato.
• Limita la concorrenza, non inviare tutto in una volta. Un piccolo pool di thread (o un semaforo asincrono) evita di colpire i limiti di frequenza; in caso di 429, fai backoff e riprova invece di trattarlo come un errore definitivo.
• Scegli il livello di qualità in base all'uso dell'immagine, non in modo uniforme: le miniature e le griglie di listino spesso bastano a low/medium, mentre le immagini principali della homepage o i creativi pubblicitari meritano high o xhigh.
• Deriva le diverse proporzioni dalla stessa immagine sorgente già modificata, non dall'originale: esegui una volta la modifica di sostituzione dello sfondo, poi richiedi da quel risultato versioni ritagliate in 1:1, 4:5 e 9:16, così ogni canale mostra esattamente la stessa presentazione del prodotto.
• Scarica o ricarica subito l'URL di output. Gli output dei task scadono; non usare URL temporanei come fonte permanente delle tue immagini.

Prezzi

gpt-image-2.5-flare fattura in base al numero di immagini prodotte, secondo il livello di qualità — stessa tariffa sia per la generazione da zero che per la modifica:

Qualità	Prezzo per immagine
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

Al livello medium, rinnovare il tema di un catalogo di 500 SKU, con una modifica di sostituzione dello sfondo per prodotto, costa circa $33,60. Consulta la pagina dei prezzi per la tabella completa e aggiornata delle tariffe di tutti i modelli.

Domande frequenti

La modifica può alterare inavvertitamente il mio prodotto? Limita il prompt di modifica a un'unica modifica («cambia solo lo sfondo...») ed elenca esplicitamente ciò che deve restare invariato (forma, colore, testo dell'etichetta, angolazione della fotocamera). Gli esempi sopra mostrano il prodotto invariato in ogni modifica.

Lo stesso modello può sia generare che modificare? Sì — gpt-image-2.5-flare è un unico ID modello. Includi image_urls per modificare una foto esistente; omettilo per generare solo dal prompt.

Quante immagini sorgente si possono passare in una chiamata di modifica? Fino a 16 tramite image_urls, ma la maggior parte delle modifiche di catalogo ne richiede una sola — quella che vuoi ridisegnare.

Come si evitano addebiti duplicati in caso di nuovo tentativo? Invia un header Idempotency-Key unico per ogni richiesta. Un nuovo tentativo con la stessa chiave restituisce il task originale invece di crearne uno nuovo.

Letture correlate

Se stai impostando la tua prima chiamata, inizia dalla guida all'API gpt-image-2.5-flare per un esempio funzionante minimo e un approfondimento sul ciclo di vita dei task asincroni. Per altri schemi di prompt oltre alla fotografia di prodotto, vedi Prompt di GPT Image 2.5 Flare: ricette copia-incolla con output reali. Per parametri e schema completi consulta la pagina del modello, mentre per le convenzioni generali dell'API (autenticazione, polling dei task, callback) vedi la documentazione hiapi.

Pronto a provarlo sul tuo catalogo? Ottieni una chiave API dalla dashboard hiapi, poi esegui l'esempio di scatto in studio qui sopra sulla tua prima foto prodotto.