Guida all'uso
Generare immagini di prodotti e-commerce con l'API HiAPI e gpt-image-2.5-sunburst/image-to-image
Immagini di riferimento, sostituzione dello sfondo, scene d'uso e una richiesta HiAPI funzionante
In questa pagina
Perché l'image-to-image è adatto alle foto di prodotti e-commerce
Il text-to-image eccelle nel creare prodotti che non esistono dal nulla, ma questo non è quasi mai ciò di cui ha bisogno un team di catalogo. Hai già il prodotto fisico, la confezione, le etichette e la palette colori — quello che ti manca sono tempo e budget per fotografare ogni SKU con ogni sfondo e ogni scena d'uso.
gpt-image-2.5-sunburst/image-to-image usa una foto esistente come ancora e vi applica istruzioni di modifica. Questo cambia la struttura dei costi delle immagini di prodotto in modo concreto:
- Fedeltà al prodotto reale. L'immagine di input porta con sé forma, materiali, colori e layout delle etichette. Il compito del modello è preservarli mentre modifica ciò che hai richiesto, invece di reinventare un prodotto approssimativo.
- Iterazione più economica. Cambiare sfondo o scena è solo una modifica al prompt, non la prenotazione di uno studio. Puoi testare diverse direzioni di scena d'uso per lo stesso SKU in un pomeriggio e tenere quella vincente.
- Coerenza dell'intero set. Poiché ogni output deriva da una foto originale comparabile, un lotto di modifiche mantiene una somiglianza che le immagini generate da zero raramente riescono a offrire.
Quando usarlo — e quando no
Scegli l'image-to-image quando il prodotto è fisso e l'ambiente è variabile: sostituzione dello sfondo per le schede prodotto dei marketplace, scene d'uso per annunci e landing page, cambio di stagionalità o localizzazione dei props. È anche uno strumento ragionevole per sistemare una foto discreta ma non perfetta.
Non usarlo quando devi generare un concetto che non è mai esistito, quando la foto sorgente è inutilizzabile (fortemente fuori fuoco, prodotto in gran parte occluso) o quando serve riprodurre con precisione da stampa il testo dell'etichetta. In questi casi una nuova ripresa o un asset vettoriale superano qualsiasi modello.
Una regola pratica: considera la foto sorgente come il dato di fatto e il prompt come un'istruzione con ambito ben definito. Ogni istruzione di modifica che scrivi dovrebbe rispondere alla domanda: “Cosa voglio conservare e cosa voglio cambiare?”. Se la richiesta lascia questo ambiguo, la qualità crolla.
L'endpoint che chiami è lo stesso descritto nella pagina del modello; il resto di questa guida spiega come alimentarlo correttamente.
Preparare immagini di riferimento che sopravvivano alla modifica
Il modello può conservare solo ciò che riesce a vedere. La maggior parte dei risultati deludenti nelle modifiche ai prodotti deriva dalla foto di input, non dal prompt. Prima di inviare qualsiasi cosa, passa la sorgente attraverso una breve checklist.
Risoluzione e nitidezza
Invia la versione più grande e pulita che hai a disposizione. Le miniature ridimensionate perdono la struttura fine che il modello deve mantenere — venature, texture, tipografia di piccolo corpo. Se l'immagine è morbida o presenta motion blur, correggila o rifai lo scatto; i filtri di nitidezza in fase di pre-elaborazione raramente aiutano e possono introdurre aloni che il modello poi amplifica.
Inquadratura e spazio negativo
Lascia spazio vuoto attorno ai bordi del prodotto. Se l'oggetto tocca la cornice, il modello non ha spazio per costruire un nuovo sfondo e tende a ritagliare o deformare il soggetto. Uno scatto singolo con margini netti su tutti i lati è molto più affidabile da modificare rispetto a un'immagine tagliata stretta, e ti dà spazio per riposizionare il prodotto nella nuova scena.
Separazione del soggetto
Non serve un ritaglio perfetto a livello di pixel, ma una separazione pulita tra prodotto e sfondo fa gran parte del lavoro. Uno sfondo uniforme e povero di dettagli (carta seamless, gradiente neutro, parete a tinta unita) è sufficiente. Gli sfondi disordinati competono con le tue istruzioni e si insinuano nell'output.
Illuminazione e prospettiva
Scatta o scegli una sorgente di cui sei disposto a conservare la direzione della luce, perché la modifica cercherà di adattarsi ad essa. Un prodotto illuminato da davanti a sinistra vorrà che la luce principale della nuova scena arrivi anch'essa da davanti a sinistra. Inoltre, mantieni un'angolazione di ripresa coerente per ogni categoria — una vista dall'alto e una vista a tre quarti non appariranno mai armoniose nella stessa riga di prodotto.
Etichette, loghi e testi
Se sul prodotto ci sono testi che il cliente deve leggere, assicurati che siano chiaramente leggibili nella sorgente. Il modello farà del suo meglio per conservarli, ma i testi piccoli o inclinati sono i primi a degradarsi. Per i testi regolamentati o critici per il brand, prevedi un passaggio di revisione umana e valuta di orientare verso la fotocamera il lato con il testo.
Una nota sull'elaborazione in batch
Quando prepari più SKU, standardizzali: stesso rapporto di ritaglio, stesso spazio negativo, stessa tonalità di sfondo. L'impegno investito in questa fase si riflette direttamente nella coerenza degli output e rende i prompt sicuri da riutilizzare su tutta la categoria.
Sostituire lo sfondo del prodotto in modo pulito
La sostituzione dello sfondo è la modifica e-commerce più comune, ed è anche il punto in cui è più facile scrivere prompt pigri. “Nuovo sfondo” non è un'istruzione — è un pio desiderio. Il modello deve sapere che aspetto ha il nuovo spazio e come il prodotto debba essere collocato al suo interno.
Descrivi lo spazio, non solo una parola
Specifica la superficie, lo sfondo e la luce. “Prodotto appoggiato su una superficie bianca opaca con sfondo a gradiente morbido, luce principale diffusa e ampia da davanti a sinistra, ombra di contatto morbida sotto il prodotto” dà al modello una scena da costruire. “Sfondo bianco” gli lascia spazio per tirare a indovinare.
Includi sempre la clausola di conservazione del prodotto
Ogni prompt di sfondo dovrebbe contenere la clausola di conservazione: mantieni invariati forma, proporzioni, colore, materiale e testo dell'etichetta del prodotto. Scriverla costa quasi nulla e riduce sensibilmente la deriva, soprattutto per oggetti dalla silhouette distintiva.
Proteggi bordi e ombre
Un ritaglio pulito nasce da prompt che citano il contatto e le ombreggiatura. Chiedi un'ombra di contatto naturale nel punto in cui il prodotto tocca la superficie e bordi nitidi sul nuovo sfondo. Se passi da uno sfondo scuro a uno chiaro, aspettati che il modello abbia bisogno di aiuto con la luce di contorno — specifica che l'illuminazione dei bordi del prodotto è coerente con il nuovo ambiente.
Adatta la luce a quella del prodotto
Se la sorgente è stata scattata con un solo softbox, non chiedere un set in studio con luce dura e drammatica. La discrepanza di illuminazione è il segno più evidente che una scheda prodotto è stata composta. Descrivi una luce plausibile per la sorgente e ottieni varietà visiva cambiando invece colore di sfondo e texture della superficie.
Vincoli della piattaforma
Se la piattaforma di destinazione richiede uno sfondo bianco puro o a tinta unita, dichiaralo esplicitamente e chiedi nessun props e nessuna giunzione visibile della superficie. Se il target è una vetrina di brand, hai più libertà — gradienti, texture sottili e un piano d'appoggio coerente sono tutti ammessi.
Itera su una variabile alla volta
Cambia prima lo sfondo, verifica che il prodotto sia ben conservato, poi regola ombre o illuminazione. Cambiando più cose in un solo prompt non puoi capire quale istruzione ha causato il fallimento, e ogni richiesta fallita consuma comunque il costo dell'output.
Collocare il prodotto in scene d'uso
Le scene d'uso sono il punto in cui l'image-to-image dà il meglio di sé: il prodotto resta riconoscibile come se stesso, mentre il mondo attorno cambia. Qui il trucco sta nelle proporzioni, nella luce e nella plausibilità.
Ancora la scena con pochi dettagli concreti
Un prompt di scena ha bisogno di specificità sufficiente a vincolare la composizione, senza prescrivere ogni pixel. Specifica l'ambiente, la superficie su cui poggia il prodotto, uno o due props di supporto e la qualità della luce. “Su un piano di lavoro in rovere invecchiato, luce mattutina che entra da una finestra a destra, tazza in ceramica e lino piegato sfocati sullo sfondo” funziona. Un lungo elenco di props no — compete con il prodotto per l'attenzione del modello.
Imposta bene le proporzioni
Esplicita le relazioni dimensionali del prodotto nel mondo reale, perché il modello non ha un righello. Una bottiglia alta e un piccolo rossetto sembrano entrambi plausibili da soli, ma insieme risultano assurdi. Citare la superficie e un riferimento riconoscibile (una mano, una tazza standard, un ripiano) dà fondamento alle proporzioni.
Adatta prima la luce alla sorgente, poi alla scena
Stai risolvendo due problemi di illuminazione contemporaneamente: l'ombreggiatura già presente sul prodotto e la luce del nuovo ambiente. Se la sorgente è illuminata in modo diffuso e uniforme, scegli una scena con luce diurna morbida, non un controluce drammatico al tramonto. Indica esplicitamente la direzione della luce e specifica che l'illuminazione del prodotto deve essere coerente con la scena. Quando le due entrano in conflitto, ottieni o un prodotto riluminato che non corrisponde più agli altri scatti, o un effetto “incollato”.
Mantieni il prodotto nitido e la scena secondaria
Specifica che il prodotto è il soggetto a fuoco nitido e che l'ambiente è leggermente sfocato. Questa singola istruzione migliora il realismo più di qualsiasi elenco di props e impedisce al modello di inventare dettagli appariscenti sullo sfondo.
Varia la scena, non il prodotto
Per le pagine di categoria, mantieni invariato il template della scena e varia un solo elemento tra gli SKU — stagione, superficie, props. Una grammatica di scena condivisa fa sì che un set di immagini d'uso si legga come un'unica campagna marketing, non come un collage di foto stock.

Una richiesta HiAPI image-to-image funzionante
Tutto passa attraverso un unico endpoint autenticato, quindi la struttura della richiesta resta invariata qualunque cosa modifichi. Gli elementi essenziali sono l'ID del modello, l'immagine sorgente e il prompt.
Richiesta
curl -X POST "https://api.hiapi.ai/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5-sunburst/image-to-image",
"image": "https://your-cdn.example.com/products/sku-1042-source.jpg",
"prompt": "Mantieni invariati forma, proporzioni, colore, materiale e testo dell'etichetta del prodotto. Sostituisci lo sfondo con una superficie grigio caldo opaca e uno sfondo a gradiente morbido, luce principale diffusa e ampia da davanti a sinistra, ombra di contatto naturale sotto il prodotto, bordi nitidi del prodotto, prodotto mantenuto come soggetto a fuoco nitido.",
"size": "1024x1024",
"n": 1
}'
Il campo image accetta un URL ospitato, oppure un payload base64 se i tuoi asset non sono accessibili pubblicamente — il base64 tiene gli SKU non pubblicati fuori da un CDN pubblico. Mantieni n a 1 durante l'iterazione; più candidati moltiplicano i costi e rendono più difficile attribuire un cambiamento di qualità a una specifica modifica del prompt.
Interpretare la risposta
L'API restituisce un corpo JSON contenente un array data; ogni elemento porta con sé l'immagine risultante (in base64 o come URL, a seconda delle impostazioni del tuo account). Controlla il timestamp di creazione nella risposta e qualsiasi campo di utilizzo incluso, e registrali insieme all'ID della richiesta per poterli verificare in seguito.
Una chiamata Python minima è la seguente:
import os, requests
resp = requests.post(
"https://api.hiapi.ai/v1/images/edits",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gpt-image-2.5-sunburst/image-to-image",
"image": source_url,
"prompt": prompt,
"size": "1024x1024",
"n": 1,
},
timeout=180,
)
resp.raise_for_status()
item = resp.json()["data"][0]
Note pratiche di integrazione
- Memorizza il prompt insieme a ogni output. Dopo qualche settimana, l'immagine vincente è riproducibile solo se hai conservato il prompt esatto e l'immagine sorgente.
- Distingui i fallimenti di trasporto dai fallimenti del modello. Timeout e risposte 5xx sono ritentabili; le richieste rifiutate per dimensioni non supportate non lo sono.
- Scarica e salva subito gli output in modo persistente, invece di affidarti a URL temporanei.
- Metti la stringa del modello nella configurazione, non sparsa nel codice, così cambiare modello in futuro richiede una sola riga.
Il riferimento dell'endpoint e i parametri supportati sono nella pagina del modello; la fatturazione lì è basata sull'output, quindi ridurre le iterazioni fallite è la leva principale per controllare i costi.

Gestire i difetti e mantenere la coerenza degli output
Anche con buoni input e prompt accurati, le modifiche ai prodotti falliscono in modi riconoscibili. Ogni modalità di fallimento ha una correzione standard.
Deriva della forma del prodotto
Sintomo: la silhouette cambia leggermente — il manico si ispessisce, la rastremazione si raddrizza. Causa: il prompt descrive più la scena che il prodotto, così il modello reinterpreta il soggetto. Correzione: metti la clausola di conservazione all'inizio, nomina esplicitamente la forma e semplifica la descrizione della scena. Se la deriva persiste, l'inquadratura della sorgente è probabilmente troppo stretta.
Testo dell'etichetta perso o distorto
Sintomo: il nome del brand diventa simboli pseudo-plausibili. Causa: il testo nella sorgente è troppo piccolo, inclinato o a basso contrasto. Correzione: parti da una sorgente più nitida e più frontale; specifica che il testo dell'etichetta e i loghi restano invariati e chiaramente leggibili; evita di aggiungere dettagli di sfondo pesanti dietro l'area dell'etichetta. Per i testi regolamentati, prevedi comunque una revisione umana.
Composizione incoerente nel set
Sintomo: ogni immagine della categoria ha proporzioni e angolazioni diverse. Causa: ritagli della sorgente e prompt per immagine incoerenti. Correzione: uniforma lo spazio negativo e l'angolazione di ripresa delle sorgenti prima di modificare, e riutilizza un template di prompt per tutto il lotto cambiando solo la variabile di scena.
Aloni sui bordi e prodotti fluttuanti
Sintomo: bordi luminosi attorno al prodotto, o oggetti senza ombra che sembrano incollati. Causa: discrepanza di illuminazione tra sorgente e scena richiesta. Correzione: chiedi esplicitamente un'ombra di contatto naturale, specifica la direzione della luce e scegli ambienti la cui illuminazione corrisponda allo scatto sorgente.
Aspetto plastico da sovra-modifica
Sintomo: texture appiattite, tessuti troppo puliti. Causa: il prompt chiede un risultato “rifinito” o “professionale” senza limiti al fotoritocco. Correzione: chiedi di conservare texture originali, grana dei materiali e segni di usura.
Regola generale
Cambia una variabile per iterazione, includi una clausola di conservazione in ogni prompt e fissa gli standard delle foto sorgente. Quando un output fallisce, chiediti prima se la foto di input è abbastanza buona — il più delle volte la risposta è no.
Integrare la modifica delle immagini nel flusso di lavoro del catalogo
Una singola richiesta funzionante non è una pipeline. Per trasformarla in output su scala di catalogo, la chiave è la disciplina ingegneristica attorno alle chiamate al modello.
Standardizza gli input all'ingestione
Costruisci un piccolo passaggio di pre-elaborazione: ritaglia a un rapporto standard, aggiungi uno spazio negativo fisso e segnala le sorgenti a bassa risoluzione o sfocate prima che raggiungano l'API. Un controllo preliminare che rifiuta input scadenti fa risparmiare più di qualsiasi ottimizzazione del prompt.
Elabora in batch per template, non per SKU
Raggruppa i prodotti in categorie e assegna a ciascuna una o due template di prompt. Esegui i batch, poi rivedi una panoramica di miniature per template. Modificare il template e rieseguire la categoria costa molto meno che scrivere prompt a mano per ogni articolo, e mantiene coerente la grammatica visiva.
Due livelli di revisione
Il primo livello è un rapido scarto: il prodotto sembra ancora se stesso? Il testo è leggibile? I bordi sono puliti? Il secondo livello è una revisione di design secondo le linee guida del brand. Automatizza il più possibile i controlli meccanici — hash delle immagini per confrontare con le sorgenti e rilevare derive gravi, verifica di risoluzione e formato sui deliverable.
Allega le informazioni di provenienza
Memorizza immagine sorgente, prompt, ID del modello e timestamp insieme a ogni output. Quando un product manager chiede perché una particolare immagine principale appare diversa, la risposta dovrebbe essere la differenza tra due record di prompt, non un'indagine.
Rilascio per fasi
Parti dalla sostituzione dello sfondo, la modifica a minor rischio; passa alle scene d'uso quando i template si sono stabilizzati. Lancia prima su una categoria, poi sull'intero catalogo, mantenendo la possibilità di rigenerare su richiesta qualsiasi singolo elemento.
Sapere dove finisce il modello
Una pipeline non sostituisce la necessità di un fotografo per gli SKU di punta, né la revisione legale delle dichiarazioni sul prodotto. Considera le modifiche generate come un livello produttivo e riserva il budget studio alle immagini in cui la fedeltà è il valore principale.
Se sei pronto a testarlo sul tuo catalogo, la struttura di richiesta sopra è tutto ciò che ti serve per iniziare a usare gpt-image-2.5-sunburst/image-to-image su HiAPI.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Guida introduttiva a Tripo H3.1: come scegliere tra tre modalità di input, parametri e prezzi
Guida pratica per sviluppatori: decisioni di integrazione e controllo dei costi nella generazione 3D
-
Guida all'uso
Generare immagini di prodotto e-commerce con qwen-image-2.1-turbo tramite l'API HiAPI
Un flusso di lavoro rapido per immagini di catalogo per sviluppatori: output PNG trasparente e richieste API eseguibili
-
Guida all'uso
Utilizzare topaz-upscale/video tramite l'API HiAPI: flusso di lavoro per il miglioramento della qualità dei video brevi
Interpolazione dei fotogrammi, impostazioni di potenziamento e una richiesta HiAPI funzionante per video verticali