Tutorial di integrazione delle API di GPT Image 2.6: scelta tra Flare e Sunburst, guida pratica all'output GIF e SVG

Prima prendi tre decisioni: canale, modalità, formato di output

Prima di scrivere la prima riga di richiesta, definisci tre cose: così non dovrai modificare il codice più volte in seguito.

Primo, scegli il canale: Flare o Sunburst. In assenza di esigenze particolari, usa Flare come predefinito: genera immagini più velocemente ed è adatto a iterazioni rapide e generazione in batch. Passa a Sunburst solo quando devi fare più round di modifica a qualità medium o superiore e ti interessa molto la coerenza di personaggi/prodotti/impaginazione. I parametri, l'utilizzo e i prezzi dei due sono identici, quindi il costo del passaggio consiste solo nel cambiare un ID modello.

Secondo, scegli la modalità: generazione da testo o da immagine. Partire da un prompt significa generazione da testo; se hai già da 1 a 16 immagini di origine e vuoi modificarle, si tratta di generazione da immagine. Attenzione: l'intervallo di formati di output disponibili è diverso: gif e svg sono disponibili solo nella generazione da testo, mentre la generazione da immagine può produrre solo png, jpeg, webp.

Terzo, scegli il formato di output: statico o animato/vettoriale. Il predefinito è png; per uno sfondo trasparente usa png o webp; per un'animazione usa gif; per un vettoriale scalabile usa svg.

Nel codice, le tre decisioni si traducono nei valori di due campi: l'ID modello e output_format. Definirli come costanti fin dall'inizio è molto più comodo che modificarli man mano durante le prove.

I quattro ID modello e i criteri di scelta tra Flare e Sunburst

L'ID modello è composto da due parti, «canale + modalità», per un totale di quattro:

• gpt-image-2.6-flare/text-to-image

• gpt-image-2.6-flare/image-to-image

• gpt-image-2.6-sunburst/text-to-image

• gpt-image-2.6-sunburst/image-to-image

Lo schema di denominazione è molto semplice: la prima parte è il canale, la seconda è la modalità. I nomi dei parametri nel corpo della richiesta, gli intervalli di valori e il criterio di tariffazione sono completamente identici sui due canali, quindi puoi incapsulare tutto in una funzione e passare il canale come parametro.

Quando è obbligatorio usare Sunburst

Sunburst cura maggiormente i dettagli: quando si fanno più round di modifica a qualità medium o superiore, i dettagli sono più coerenti. Gli scenari tipici sono le micro-modifiche ripetute con personaggi fissi, aspetto del prodotto fisso e impaginazione fissa. Se il tuo flusso è «genera prima, poi modifica tre volte», i vantaggi di Sunburst si vedranno nei round successivi.

Quando restare su Flare

Generazione di singole immagini, produzione in batch, verifica rapida dell'effetto di un prompt: in questi scenari Flare, essendo più veloce, è la scelta migliore. Poiché i prezzi dei due sono identici, scegliere Flare non comporta alcuno svantaggio economico.

Consiglio pratico: in fase di sviluppo usa Flare in modo uniforme per validare parametri e formati; una volta in produzione, passa al altro canale solo per i casi che richiedono più round di modifica. Nella pagina del modello puoi prima consultare la descrizione dei campi di Flare text-to-image e Sunburst text-to-image.

Come compilare i parametri chiave della generazione da testo

I parametri principali della generazione da testo sono sette; di seguito spieghiamo valori e vincoli di ciascuno.

quality e resolution

quality accetta low / medium / high / xhigh / max e determina il livello di dettaglio; è anche l'unico criterio di tariffazione per le GIF. resolution accetta 1K / 2K / 4K, con valore predefinito 1K. Questi due parametri determinano insieme il prezzo per singola immagine e sono anche le due manopole per il controllo dei costi.

complexity

Accetta low / medium / high, con valore predefinito high, e indica il livello di pianificazione. È indipendente da quality: uno gestisce la profondità della pianificazione della composizione, l'altro il livello di dettaglio dell'immagine. Non modificare complexity solo perché hai abbassato quality: i due non sono collegati.

aspect_ratio

Accetta auto o uno dei 15 rapporti. C'è una regola facile da sbagliare: quando generi una GIF, aspect_ratio non va passato oppure va passato come auto, perché il rapporto della GIF è determinato da frame_size e un conflitto tra i due non avrebbe senso.

output_format e output_compression

output_format accetta png (predefinito) / jpeg / webp / gif / svg. output_compression accetta 0–100 ed è efficace solo per jpeg e webp; passare un parametro di compressione a png non funzionerà come previsto.

background

Accetta auto / opaque / transparent. transparent deve essere abbinato a png o webp: se vuoi uno sfondo trasparente ma hai scelto jpeg, devi cambiare formato.

Basta ricordare un solo principio su questi vincoli: il formato limita a sua volta gli altri parametri: gif blocca la fonte del rapporto, jpeg/webp accettano la compressione, transparent è supportato solo da png/webp.

Output GIF: frame_size, numero di frame e limiti di dimensione

Le GIF possono essere generate solo dalla generazione da testo; i parametri sono concentrati sui frame.

frame_size

Larghezza e altezza in pixel di ogni frame, scritta nella forma «larghezzaxaltezza» come 512x512; entrambi i lati devono essere multipli di 16, valore predefinito 512x512. Determina anche il rapporto complessivo della GIF, quindi in questo caso non passare più aspect_ratio. Attenzione: non accetta notazioni come 1:1, devono essere valori in pixel.

frame_count e frame_duration_ms

frame_count accetta da 2 a 16, valore predefinito 9. C'è una limitazione legata alle dimensioni: 768x768 supporta al massimo 12 frame. frame_duration_ms non è inferiore a 20, valore predefinito 200, arrotondato a multipli di 10 ms.

Tre limiti rigidi

Il fotogramma complessivo della GIF deve inoltre rispettare: ogni lato non superiore a 3840, pixel totali non superiori a 8.294.400, rapporto larghezza/altezza non superiore a 3:1. Se si superano, la richiesta viene rifiutata già in fase di invio e non viene addebitato alcun costo; quindi questi errori non comportano spese, ma fanno perdere tempo nel debug.

Un corpo di richiesta GIF minimo funzionante:

{
  "model": "gpt-image-2.6-flare/text-to-image",
  "prompt": "a bouncing paper plane on white",
  "output_format": "gif",
  "frame_size": "512x512",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "medium"
}

Per produrre da 13 a 16 frame, usa frame_size 512x512 o inferiore; 768x768 supporta al massimo 12 frame.

Come usare l'output SVG e come viene calcolato il prezzo

Anche SVG è disponibile solo nella generazione da testo; la generazione da immagine non accetta questo formato. Per usarlo basta impostare output_format su svg e compilare gli altri parametri come nella normale generazione da testo; se vuoi uno sfondo trasparente con background, tieni comunque presenti le regole di abbinamento dei formati.

Criterio di tariffazione

SVG viene calcolato come il prezzo del PNG dello stesso livello più $0,030. Ad esempio, un PNG low 1K costa $0,023, quindi lo SVG dello stesso livello costa $0,053; un PNG high 2K costa $0,090, quindi lo SVG costa $0,120. Più alto è il livello, più costoso è lo SVG, ma i $0,030 aggiuntivi restano invariati.

Consigli d'uso

SVG è adatto a obiettivi come loghi, icone e diagrammi che richiedono ridimensionamento senza perdita di qualità. Se la tua pipeline a valle alla fine richiede comunque bitmap, usare png è più semplice: il sovrapprezzo per il vettoriale non porta alcun beneficio.

Generazione da immagine: immagini di origine, maschera e immagine annotata in alternativa

L'input della generazione da immagine è costituito da 1 a 16 immagini di origine, in formato jpeg / png / webp; l'output è solo png / jpeg / webp.

mask_url e markup_url: solo uno dei due

• mask_url: un PNG RGBA delle stesse dimensioni della prima immagine di origine, in cui i pixel trasparenti indicano le aree da modificare.

• markup_url: un'immagine annotata PNG trasparente che cerchia sulla figura le posizioni da modificare; l'annotazione stessa non compare nel risultato generato.

I due sono mutuamente esclusivi: se li passi entrambi, la richiesta viene rifiutata. La logica di scelta è semplice: se vuoi che il sistema modifichi in modo preciso solo un blocco di pixel, usa la maschera; se vuoi solo indicare «all'incirca questo punto» senza essere vincolato da bordi rigidi, usa l'immagine annotata.

Anche fuori dalla maschera possono esserci cambiamenti

Quando usi mask_url, devi aspettarti che anche le aree fuori dalla maschera possano subire lievi cambiamenti. Se il tuo caso d'uso richiede che le aree non selezionate restino invariate a livello di pixel, questo non è garantito con la generazione da immagine: dovrai gestirlo tu in fase di compositing.

Fatturazione

La generazione da immagine usa la stessa tabella prezzi della generazione da testo, con $0,012 aggiuntivi per ogni immagine di riferimento. Con low 1K e 1 immagine il costo è $0,035; con 16 immagini è $0,215. Passa solo le immagini di riferimento realmente necessarie.

Esempio di corpo della richiesta:

{
  "model": "gpt-image-2.6-flare/image-to-image",
  "prompt": "change the background to warm sunset",
  "image_urls": ["https://your-cdn/source.png"],
  "mask_url": "https://your-cdn/mask.png",
  "output_format": "png"
}

Per i dettagli dei campi puoi consultare la pagina Flare image-to-image.

Stima dei costi: calcolo del prezzo per singola immagine in base al livello di qualità e alle dimensioni

Innanzitutto ricorda i tre criteri di tariffazione:

• Generazione da testo (png/jpeg/webp): il prezzo per singola immagine è determinato insieme da quality e resolution.

• SVG: prezzo del PNG dello stesso livello più $0,030.

• GIF: tariffato solo in base a quality, indipendentemente dalla risoluzione: low $0,070, medium $0,124, high $0,150, xhigh $0,266, max $0,598.

• Generazione da immagine: prezzo della stessa tabella, con $0,012 aggiuntivi per ogni immagine di riferimento.

Come stimare una singola immagine

Quattro passi: determina la modalità (generazione da testo o da immagine) → determina il formato (gif considera solo la qualità, svg aggiunge $0,030, gli altri considerano qualità × risoluzione) → consulta il prezzo unitario del livello corrispondente → per la generazione da immagine aggiungi $0,012 × numero di immagini di riferimento. I livelli più usati della generazione da testo: low 1K $0,023, medium 1K $0,041, high 1K $0,049, high 2K $0,090, high 4K $0,160.

Quali casi non vengono addebitati

Le richieste rifiutate in fase di invio vengono rimborsate per intero, senza addebito. Sono inclusi parametri non validi (ad esempio background=transparent abbinato a jpeg, oppure aspect_ratio passato a gif) e dimensioni GIF fuori limite. Questo significa che gli errori di validazione dei parametri non bruciano denaro, ma rallentano le iterazioni; si consiglia di fare un controllo preliminare lato client.

Tutti i 15 livelli sono disponibili nella pagina dei prezzi. Per confrontare il metodo di tariffazione della generazione precedente, puoi vedere GPT Image 2.5 Flare text-to-image.

In sintesi: predefinito Flare + generazione da testo + png; passa a Sunburst in caso di più round di modifica; cambia output_format quando servono animazioni o vettoriali.