Guida API GPT Image 2.5: Generazione e modifica di immagini con Sunburst e Flare

Utilizza Image API per generazione e modifica diretta in un unico passaggio. Quando la creazione di immagini fa parte di un dialogo o di un flusso multi-passaggio, utilizza Responses API. In Image API, seleziona direttamente gpt-image-2.5-sunburst o gpt-image-2.5-flare.

Seleziona prima l'interfaccia

L'API delle immagini fornisce endpoint per la generazione e la modifica. L'API di risposta supporta la generazione iterativa di immagini come strumento e può mantenere l'input e l'output delle immagini nel contesto. Questa decisione architetturale è più importante della sintassi dell'SDK.

Modalità di generazione minima

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "un'illustrazione di design pulito che raffigura una biblioteca solare, senza elementi testuali"
  size: "1536x1024",
  quality: "Media",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

Conservare la chiave API lato server e tenerla lontana dal controllo del codice sorgente.

Controllo dell'output

Entrambi i modelli supportano dalla modalità automatica alla massima qualità, dimensioni personalizzate entro i limiti ufficiali, formati PNG/JPEG/WebP, compressione JPEG/WebP e sfondi trasparenti o opachi. Per il canale Alpha, utilizza i formati PNG o WebP.

Modalità di modifica

Utilizza una o più immagini per chiamare l'endpoint di modifica e fornisci un prompt che separi le modifiche dai dettagli da conservare. Verifica il tipo e la dimensione dell'input prima di inviarlo. Assegna un ruolo a ciascun riferimento.

Verifica di produzione

Memorizza l'ID della richiesta, il modello o snapshot, la versione del prompt, le dimensioni, la qualità, il formato di output, le informazioni di riferimento, la latenza e il risultato accettato. Riprova solo per guasti temporanei; senza modificare la richiesta, non riprovare automaticamente output con errori semantici.

Routing del modello

Instradare le attività quotidiane a Flare e quelle ad alta precisione a Sunburst. Utilizzare un benchmark fisso, evitando di presumere che un modello più veloce sia più economico, poiché le attuali tariffe dei token corrispondono.

Gestione degli errori

Gestione dell'autenticazione, verifica dell'organizzazione, limitazione della frequenza, dimensioni non valide, moderazione dei contenuti e output vuoti. Utilizzare una strategia di backoff esponenziale con jitter per errori temporanei idonei e limitare il numero di tentativi. Non registrare mai inutilmente dati di immagini private.

Animazioni a valle

Dopo aver decodificato e approvato l'immagine, memorizza le informazioni sulla fonte e passa l'asset al flusso di lavoro successivo. Quando un'immagine statica deve diventare uno storyboard, un video o un'animazione guidata da personaggi, Elser AI è pertinente. Verifica le opzioni di caricamento e modello supportate nel prodotto in tempo reale.

Endpoint di generazione e endpoint di modifica

Utilizza la funzione di generazione per creare nuove immagini a partire da testo. Utilizza la funzione di modifica quando una o più immagini esistenti definiscono il soggetto o lo stato iniziale. Per modifiche con più riferimenti, invia gli input in un ordine stabile e identifica tale ordine nel prompt. Verifica il tipo di file e le dimensioni prima della richiesta, in modo che gli input errati falliscano localmente.

API di risposta per il lavoro iterativo

L'API Responses è molto utile quando gli utenti creano immagini, le valutano in modo dialogico e richiedono modifiche successive. Gli strumenti di generazione di immagini possono partecipare a un flusso di risposta più ampio e l'ID del file immagine può essere mantenuto nel contesto. Ciò riduce il lavoro di assemblaggio lato applicazione, ma il prodotto richiede ancora uno stato e un controllo delle versioni chiari. "Come prima" non è sufficiente come vincolo chiave; riformula.

Architettura dell'applicazione più sicura

Mantenere il client, la coda delle attività, l'archiviazione degli asset e l'archiviazione dei metadati indipendenti tra loro. Il client invia una breve descrizione. Il server verifica la descrizione e crea un'attività. Il worker chiama OpenAI, decodifica il risultato e lo memorizza sotto l'ID dell'asset generato. I metadati registrano lo snapshot del modello, il prompt, le impostazioni, i riferimenti e i risultati della moderazione. Il client riceve un URL dell'asset valido per un breve periodo, non le credenziali originali.

Le chiamate a lunga esecuzione non dovrebbero occupare le fragili richieste del browser. I prompt complessi possono richiedere molto tempo, quindi è opportuno mostrare lo stato di elaborazione, completamento e fallimento. Rendi l'invio delle attività idempotente per evitare costi duplicati in caso di tentativi di ripetizione da parte del client.

Regole di verifica

Verifica che le dimensioni personalizzate rispettino i multipli di 16, i margini, le proporzioni e i limiti di pixel totali previsti dalla documentazione. Quando lo sfondo è trasparente, è richiesto l'uso del formato PNG o WebP. Limita il valore di compressione all'interno dell'intervallo supportato. Sono consentiti solo parametri di qualità e modello noti. Rifiuta la mancanza di prompt prima della chiamata API.

Affidabilità e Osservabilità

Registra l'ID della richiesta, lo stato HTTP, la categoria dell'errore, il numero di tentativi e la latenza, senza registrare immagini private o informazioni riservate. Utilizza un backoff esponenziale con jitter per i limiti di velocità di ripetizione e per gli errori del server che lo consentono. Non ripetere così com'è l'autenticazione, i parametri non validi o gli errori di policy. Imposta un limite massimo al numero di tentativi e restituisci messaggi di prodotto utili.

Monitor:

Tasso di successo e tasso di accettazione delle immagini.
Latenza p50 e p95 suddivise per modello e qualità.
Token di input e output.
Attività di riprova e ripetizione.
Risultato della revisione.
Archiviazione e consegna fallite.

Sicurezza e Diritti

Conservare la chiave API nel gestore di chiavi lato server. Implementare il controllo degli accessi per le immagini sorgente e quelle generate. Impostare regole di conservazione, rimuovere i metadati che non dovrebbero essere esposti e registrare i diritti degli utenti sui materiali caricati. OpenAI sottolinea che l'accesso al modello di immagini GPT potrebbe richiedere una verifica organizzativa; gestiscilo come prerequisito di onboarding, non come imprevisto in fase di esecuzione.

Strategia degli snapshot

Utilizza ID senza data per ottenere aggiornamenti continui del modello. Quando la riproducibilità è più importante, fissa uno snapshot con data. Prima di modificare il traffico di produzione, valuta il nuovo snapshot utilizzando lo stesso benchmark. Memorizza l'identificatore effettivo del modello restituito o configurato per ogni risorsa.

Se l'articolo di avvio contiene codice, mostra accanto la data di verifica con la data. I lettori devono comprendere che la disponibilità del modello, la sintassi dell'SDK, i limiti di velocità e i requisiti organizzativi potrebbero cambiare indipendentemente dall'architettura concettuale dell'articolo.

Contratti di richiesta tipizzati

Definire uno schema interno anche se il modello di immagine stesso non fornisce output strutturati. Un'attività può includere prompt (prompt), workflow (flusso di lavoro), model (modello), quality (qualità), width (larghezza), height (altezza), format (formato), background (sfondo), compression (compressione), un ID risorsa di riferimento e una chiave idempotente. Validarlo prima di convertirlo in una chiamata SDK.

Non esporre nomi di modelli o percorsi di file arbitrari dal browser. Mappa il piccolo set di opzioni visibili al client su valori approvati dal server. Risolvi i riferimenti tramite ID di asset controllati dall'accesso e verifica che l'utente corrente abbia il permesso di leggere tali asset.

Bozza della richiesta di modifica

import OpenAI from "openai"; import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({ model: "gpt-image-2.5-sunburst", image: [fs.createReadStream("approved-character.png")], prompt: `Cambia solo il cappotto in lana verde scuro. Mantieni il colore del viso, dei capelli, degli occhi, la posa, le mani, la composizione e lo sfondo. Non aggiungere testo, gioielli o altre persone. size: "1024x1536", quality: "alta", output_format: "png" });

const bytes = Buffer.from(result.data[0].b64_json, "base64"); fs.writeFileSync("character-green-coat.png", bytes);


Le interfacce SDK esatte potrebbero evolversi, quindi prima della distribuzione verifica gli esempi confrontandoli con la guida ufficiale corrente. Il codice di produzione dovrebbe gestire lo streaming o il buffering in modo responsabile, verificare la presenza delle risposte e memorizzarle in modo atomico, senza presumere che ogni chiamata restituisca dati utilizzabili.

## Idempotenza e costo della ripetizione

Il doppio clic dell'utente o un tentativo di rete potrebbero causare l'invio due volte dello stesso costoso compito di generazione. Assegna una chiave idempotente al momento della creazione del compito, persisti il compito prima della distribuzione e, quando la stessa chiave si ripresenta, restituisci il compito esistente. I processi di lavoro dovrebbero acquisire il compito una sola volta e registrare lo stato finale.

Se intendi generare più varianti, rappresentalo come un'operazione di prodotto esplicita, non come un tentativo accidentale. L'API per le immagini supporta la generazione di più immagini tramite il parametro `n` nella documentazione, ma i tuoi costi e il modello di moderazione dovrebbero conteggiare ogni output.

## Esperienza utente di revisione e fallimento

Tutti i prompt e le immagini devono essere sottoposti a filtri di sicurezza. Evita di rivelare dettagli sensibili della revisione interna, ma fornisci agli utenti indicazioni sufficienti per modificare richieste legittime. Distingui i rifiuti per policy da impostazioni non valide, autorizzazioni, limiti di frequenza e guasti temporanei del servizio.

Quando Sunburst non è disponibile, non sostituirlo silenziosamente con altri modelli, poiché ciò potrebbe violare gli accordi di qualità o contrattuali. È necessario restituire uno stato chiaro o utilizzare una soluzione alternativa solo se il prodotto ha già divulgato e documentato tale comportamento.

## Archiviazione e consegna degli asset

Decodifica il base64 in memoria e imposta un limite di dimensione, verifica il formato dichiarato, genera un checksum e archivia il file originale immutabile. Genera separatamente le miniature. Servi tramite URL firmati a breve scadenza e con i tipi di contenuto appropriati. Conserva il canale alfa di PNG/WebP trasparenti, evitando che conversioni con perdita compromettano i deliverable.

Archiviare suggerimenti e materiali di riferimento con controlli di accesso adeguati, in base al loro livello di sensibilità. Definire le politiche di conservazione e cancellazione. I file generati senza fonte sono difficili da verificare, riprodurre o consegnare in modo sicuro al progetto Elser Animation.

## Lista di controllo pre-pubblicazione

- Accesso all'account e all'organizzazione confermato.
- La chiave API è lato server e può essere ruotata.
- ID del modello e regole dimensionali sono stati inseriti nella whitelist.
- L'invio dei compiti è idempotente.
- Numero di tentativi limitato e classificato.
- L'utilizzo, la latenza e l'accettazione sono monitorati.
- Le immagini e i metadati hanno regole di conservazione.
- Per output sensibili all'identità, al marchio e al testo, è prevista una revisione manuale.
- È stata registrata una strategia di snapshot con data e un percorso di rollback.

## Domande frequenti

### Quale API dovrei scegliere?
Image API è utilizzato per la generazione/modifica diretta; Responses API è utilizzato per esperienze di immagini conversazionali o multi-step.

### Posso richiedere più immagini?
L'API Image supporta il parametro `n` per output multipli nella documentazione.

### L'API restituisce un URL?
La guida corrente mostra i dati dell'immagine codificati in base64 dell'API delle immagini; decodificali e conservali in modo sicuro.

## Conclusioni

Un'integrazione affidabile combina un routing chiaro del modello con una verifica rigorosa, osservabilità e revisione delle risorse. Costruisci prima la richiesta diretta minima, aggiungendo lo stato della conversazione o le animazioni a valle solo quando il percorso dell'immagine principale è affidabile.