Guida all'uso
muse-image-1.0/text-to-image per immagini di prodotti e-commerce: guida al flusso di lavoro per sviluppatori
Template di prompt per angolazioni e illuminazione, scelta delle dimensioni e richieste in batch tramite l'API HiAPI
In questa pagina
Perché il text-to-image è adatto ai carichi di lavoro dei prodotti e-commerce
Un catalogo è per natura ripetitivo: lo stesso prodotto, fotografato da alcune angolazioni, con la stessa illuminazione, sullo stesso sfondo, in poche dimensioni. È proprio questa ripetitività che i modelli text-to-image sanno gestire bene — non per sostituire gli scatti in studio dei prodotti di punta, ma per coprire in modo economico e coerente la coda lunga del catalogo.
Scenari in cui la generazione è davvero utile:
- Varianti in grande quantità. Combinazioni di colori, lievi differenze tra SKU e revisioni del packaging, dove il costo di un nuovo servizio fotografico supera il valore dell'immagine stessa.
- Segnaposto e materiali pre-lancio. Pagine di elenco, materiali per revisioni interne e test A/B che devono apparire realistici prima che arrivino le foto definitive.
- Esplorazione della composizione. Provare una vista dall'alto flat lay rispetto a una hero a 45 gradi prima di impegnare fotografo e studio.
Scenari non adatti: dichiarazioni soggette a normative, testi di packaging che devono essere perfettamente leggibili e immagini principali in cui il cliente confronterà texture e finiture nel dettaglio. Per queste servono ancora una fotocamera e una persona.
Per lo sviluppatore il modello mentale è una pipeline. Si inserisce una descrizione strutturata del prodotto, si renderizza un template di prompt, il modello restituisce una o più immagini e un controllo QA decide cosa può essere pubblicato nel negozio. Ogni sezione che segue spiega come rendere questa pipeline noiosa e ripetibile, non intelligente.

Chiamare muse-image-1.0/text-to-image tramite HiAPI
Tutte le richieste passano attraverso la stessa interfaccia HiAPI, quindi ti autentichi una sola volta e mantieni un unico client per tutti i modelli che chiami. L'identificatore del modello è muse-image-1.0/text-to-image; la richiesta trasporta il prompt, la scelta delle dimensioni di output e qualsiasi opzione di generazione singola tu voglia fissare.
Dal punto di vista strutturale, una singola generazione consiste nel: costruire il payload della richiesta, inviarlo in POST tramite il client HiAPI, leggere l'oggetto risultato restituito e rendere persistente il riferimento dell'immagine insieme all'ID del prodotto a cui appartiene. Due abitudini che vale la pena adottare fin dalla prima chiamata:
- Conserva i prompt in variabili, non inline nella richiesta. Li riutilizzerai e confronterai centinaia di volte.
- Registra il prompt esatto renderizzato per ogni output. Tre settimane dopo, quando un'immagine sembrerà sbagliata, il prompt sarà la tua unica base per il debug.
import os
from hiapi import HiAPI
client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])
prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")
result = client.images.generate(
model="muse-image-1.0/text-to-image",
prompt=prompt,
size="1024x1024",
)
save_asset(product_id=product.id, angle="three-quarter", result=result)
Tratta size come parte del template, non come un ripensamento — lo stesso prompt può ricomporre il soggetto in proporzioni diverse. Le sezioni successive coprono sia la struttura del prompt sia le decisioni sulle dimensioni.

Template di prompt per angolazioni di scatto coerenti
La coerenza in un catalogo deriva da uno scheletro di prompt fisso, in cui si sostituiscono solo pochi slot. Se ogni prompt viene scritto da zero, ogni immagine risulterà leggermente diversa. Costruisci un template per ogni tipo di scatto e mantieni il linguaggio descrittivo della fotocamera identico byte per byte su tutti i prodotti.
Uno scheletro funzionante:
{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}
Solo subject_block cambia con il prodotto. camera_block è una costante per ogni angolazione:
- Hero / vista a tre quarti:
product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins - Prospetto frontale:
straight-on front view, camera at product mid-height, centered, no perspective tilt - Flat lay dall'alto:
directly overhead top-down view, product centered, flat lay composition - Dettaglio ravvicinato:
close-up macro view of the product surface, shallow depth of field
Due regole rendono tutto questo efficace nella pratica:
- Dichiara l'angolazione due volte. Un'angolazione esplicita più una clausola di inquadratura (come "full product in frame with even margins") è più affidabile di una delle due da sola.
- Evita riferimenti relativi. "Stessa angolazione dell'immagine precedente" non significa nulla per un modello text-to-image; ogni prompt deve reggersi da solo.
Conserva i template nel controllo di versione insieme al codice di rendering. Quando modifichi camera_block, incrementa la versione e rigenera un piccolo campione prima di fare commit — un cambiamento di formulazione è un cambiamento su tutto il catalogo.
Template di prompt per illuminazione e sfondo
Illuminazione e sfondo sono ciò che fa sembrare un insieme di immagini generate parte di un'unica sessione fotografica anziché un mucchio di immagini scollegate. Entrambi appartengono alla parte costante del template e richiedono direzione e morbidezza esplicite.
Linguaggio sull'illuminazione che si trasferisce in modo affidabile:
- Direzione:
key light from camera left,light from upper right,soft overhead light. La direzione è la leva di coerenza più diretta — fissala per ogni tipo di scatto. - Qualità:
soft diffused light,large softbox, gentle shadows,hard directional light with defined shadow edge. - Riempimento e riflessi:
subtle fill from the right, low-contrast shadows,clean highlight on the top surface.
Linguaggio per lo sfondo:
- Studio senza giunzioni:
on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product. - Piano d'appoggio lifestyle:
resting on a matte stone surface, softly out-of-focus neutral background. - Pronto per il ritaglio:
isolated on a plain white background, product fully in frame, generous margins for cropping.
Due avvertenze pratiche. Primo, più la superficie del prodotto è riflettente, più devi essere preciso nel descrivere l'illuminazione, perché la posizione dei riflessi è l'aspetto del prodotto. Secondo, non mescolare gli sfondi all'interno dello stesso tipo di scatto — un gruppo di riquadri di una griglia dovrebbe condividere lo sfondo, altrimenti la griglia sembrerà un collage di tre fornitori diversi. Fissa questi blocchi come costanti e modificali solo intenzionalmente.
Scegliere dimensioni di output e proporzioni
Prima di passare al batch, decidi le dimensioni in base al punto di utilizzo, perché rieseguire con dimensioni diverse è una rigenerazione completa, non un ridimensionamento. Mappa prima il punto di utilizzo sulla proporzione, poi sulla dimensione in pixel effettivamente renderizzata dal frontend.
- Griglie e riquadri di categoria: quadrato. I ritagli delle griglie di prodotti sono imprevedibili, quindi una composizione quadrata con margini ampi si adatta alla maggior parte dei layout a riquadri.
- Pagine di dettaglio prodotto: quadrato o 4:3, dimensionato per il visualizzatore zoom anziché per la miniatura. Se la pagina di dettaglio ritaglia a un rapporto fisso, allineati esattamente e non combattere con il CSS.
- Banner e strisce hero: formato ampio, con un'area sicura pianificata esplicitamente. Chiedi che il prodotto sia centrato e che ai lati ci sia spazio negativo per il testo di marketing.
- Email e social: rispetta le proporzioni native della piattaforma; rigenerare costa meno che aggiungere bordi.
Alcune regole empiriche:
- Scegli una dimensione canonica per ogni punto di utilizzo e riusala. Dimensioni miste in un'unica griglia di riquadri producono differenze di qualità visibili.
- Non ingrandire le immagini generate per riempire un punto più grande. Genera più grande e poi riduci.
- Ricontrolla la composizione dopo aver cambiato proporzione. Un hero a 45 gradi composto per il quadrato potrebbe perdere la base del prodotto in un ritaglio ampio; adegua di conseguenza la clausola di inquadratura in
camera_block. - Salva le dimensioni nel record del job. Quando in seguito rivedrai gli output, le dimensioni fanno parte del contesto, non sono rumore nei metadati.
Richieste in batch e gestione dei risultati per singola voce
Alla scala di un catalogo, l'unità di lavoro è il job, non la richiesta: un prodotto, un tipo di scatto, una dimensione, un prompt renderizzato. Modella prima i job come dati e inviali tramite una coda con concorrenza limitata, così un errore è una riga da rieseguire, non un pomeriggio perso.
Un ciclo robusto fa quattro cose:
- Renderizza il prompt in modo deterministico: dal template più i campi del prodotto, e memorizza la stringa renderizzata sul job.
- Limita la concorrenza: a quanto il tuo account e lo storage a valle riescono a sopportare; non lanciare tutto il catalogo in una volta.
- Gestisci i risultati per singola voce. Le operazioni in batch riescono o falliscono voce per voce, quindi scrivi ogni risultato sotto il suo
job_ide non presumere mai che l'intero batch sia atomico. - Riprova con backoff solo per errori transitori. Gli errori di validazione — prompt malformati, dimensioni non supportate — falliranno allo stesso modo a ogni tentativo, quindi classifica prima di riprovare.
for job in queue.fetch_pending(limit=50):
try:
result = client.images.generate(
model="muse-image-1.0/text-to-image",
prompt=job.prompt,
size=job.size,
)
db.record_success(job.id, result)
except TransientError as e:
queue.requeue(job.id, backoff=e.retry_after)
except ValidationError as e:
db.record_failure(job.id, reason=str(e))
Mantieni una colonna di stato per ogni job (pending, done, failed) e una vista dead letter per i fallimenti. Quando un batch si completa, riporta i conteggi per tipo di scatto e dimensione, non solo un totale — è lì che si nascondono le regressioni.
Checklist QA prima di pubblicare le immagini generate
Le immagini generate richiedono un cancello, e il cancello dovrebbe essere una checklist con una persona a presidiarla. I controlli automatizzati catturano i problemi economici; i revisori catturano quelli costosi.
Controlli automatizzati prima della revisione:
- Proporzioni e dimensioni in pixel corrette per il punto di utilizzo previsto.
- Nessun output visibilmente corrotto; i file si aprono e si decodificano correttamente.
- Il colore corrisponde a quello atteso quando il prompt specifica un colore del prodotto.
- I margini per la tolleranza di ritaglio sono presenti nei riquadri della griglia.
Revisione umana prima della pubblicazione:
- Il prodotto sembra questo prodotto — forma, proporzioni, ferramenta e finiture?
- Ci sono testi, loghi o copy di packaging inventati? Il testo generato è un punto di fallimento comune e anche un rischio legale nel negozio.
- Illuminazione e sfondo sono coerenti con il resto del gruppo alla dimensione miniatura, non solo a piena dimensione.
- Nessun oggetto estraneo, componente aggiuntivo o riflesso illogico nell'inquadratura.
- Dichiarazioni promozionali ed etichette soggette a normative non sono state alterate dalla generazione; queste immagini devono passare dal flusso fotografico.
Registra revisore e versione del prompt per ogni asset approvato. Quando arriva un reclamo di un cliente o una richiesta di rimozione, questa traccia ti permette di trovare in una volta tutte le immagini interessate — e di rigenerare o ritirare l'intero set.
Inizia con un tipo di scatto, una dimensione e un piccolo campione di prodotti, esegui attraverso l'interfaccia HiAPI e amplia i template solo dopo che gli output hanno superato la revisione.
Articoli correlati
Vedi tutti gli articoli →-
Guida all'uso
Guida introduttiva a gpt-6.2-sol: limiti delle capacità, integrazione API e note sui prezzi per token
Punti decisionali e pratici per l'integrazione rivolti ai team di ingegneria
-
Guida all'uso
Guida introduttiva a gpt-6.2-astra: confini delle capacità del modello testuale, punti di integrazione e controllo dei costi
-
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