dall-e-3, il modello con capacità di rendering del testo più avanzata gpt-image-1, la nuova generazione gpt-image-2, e la serie di modelli nano-banana / nano-banana-2 / nano-banana-pro accessibili tramite la stessa interfaccia. Tutti questi modelli possono generare immagini di alta qualità basate su descrizioni testuali.
Questo documento descrive principalmente il flusso di utilizzo dell’API OpenAI Images Generations, che permette di utilizzare facilmente le funzionalità di generazione immagini della serie OpenAI.
Procedura di Richiesta
Per utilizzare OpenAI Images Generations API, è possibile visitare la pagina OpenAI Images Generations API e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per le richieste:
Se non si è ancora effettuato l’accesso o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere; dopo il login, si tornerà automaticamente alla pagina corrente.
Alla prima richiesta viene offerto un credito gratuito per utilizzare l’API senza costi.
Modello GPT-Image-2
gpt-image-2 è il modello di generazione immagini di nuova generazione di OpenAI, che presenta miglioramenti evidenti rispetto a dall-e-3 e gpt-image-1 nei seguenti aspetti:
- Maggiore capacità di seguire istruzioni: comprende accuratamente istruzioni strutturate complesse come composizione, conteggio e relazioni spaziali.
- Rendering del testo più nitido: in scenari come poster, menu, infografiche, loghi, il testo in inglese e i numeri sono quasi privi di errori.
- Espressione stilistica più ricca: supporta nativamente stili come ritratti cinematografici, poster vintage, illustrazioni per bambini, fotografia di prodotto, infografiche, ecc.
- Supporto nativo per più proporzioni + alta risoluzione: copre 5 proporzioni (1:1, 4:3, 3:4, 16:9, 9:16) con 3 livelli di risoluzione (1K / 2K / 4K).
model su gpt-image-2. L’URL restituito è un link permanente dell’immagine ospitata su platform.cdn.xhuoapi.ai, apribile direttamente nel browser o incorporabile in pagine web.
Valori supportati per size e livelli di tariffazione
gpt-image-2 verifica solo il formato di size: se non è auto o stringa vuota, deve corrispondere a WIDTHxHEIGHT (es. 1024x1024, 2048x1152, 800x600); qualsiasi altro formato restituisce 400. La tariffazione è divisa in due livelli:
- Prezzo standard 1K: input corrispondente a una delle dimensioni 1K consigliate nella tabella sottostante, o alias comuni 1K upstream (
1254x1254,1672x941,941x1672— queste sono dimensioni effettive restituite upstream per 1K, riutilizzandole non si cambia tariffa). - Altri livelli (1.5×): qualsiasi dimensione non inclusa nel set 1K sopra, comprese le preimpostazioni 2K / 4K nella tabella e qualsiasi
WIDTHxHEIGHTpersonalizzato.
| Proporzione | 1K (Prezzo standard) | 2K consigliato (×1.5) | 4K consigliato (×1.5) |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 4:3 | 1536x1024 | 2048x1536 | 3264x2448 |
| 3:4 | 1024x1536 | 1536x2048 | 2448x3264 |
| 16:9 | 1792x1024 | 2048x1152 | 3840x2160 |
| 9:16 | 1024x1792 | 1152x2048 | 2160x3840 |
Puoi anche passaresize: "auto"o omettere il camposize, in tal caso il modello sceglierà la dimensione predefinita e verrà applicato il prezzo standard 1K. Per il livello 1K, l’output upstream non garantisce un allineamento preciso dei pixel — ad esempio, passando1024x1024potresti ricevere1254x1254, mantenendo la proporzione. Se la dimensione ricevuta viene riutilizzata comesize, sarà comunque tariffata come 1K. Le chiamate 4K richiedono solitamente 4–8 minuti; si consiglia di usare il meccanismo di callback asincronocallback_urldescritto più avanti.
Riguardo al parametroDi seguito alcuni esempi reali per mostrare le capacità dingpt-image-2non supportan > 1: questo parametro viene ignorato silenziosamente; indipendentemente dal valore din, ogni richiesta restituisce una sola immagine e viene fatturata come una sola. Per ottenere più immagini contemporaneamente, è necessario effettuare più richieste concorrenti (si consiglia di variarepromptoseedper evitare immagini troppo simili). Questa limitazione vale anche pergpt-image-1/gpt-image-1.5e la serienano-banana. Solodall-e-2supporta nativamenten > 1;dall-e-3supporta solon = 1.
gpt-image-2.
Scenario 1: Ritratto cinematografico
Nel prompt si possono usare termini cinematografici (pellicola 35mm, profondità di campo ridotta, luci al neon, ecc.) per controllare atmosfera e texture. Esempio di codice Python:
Scenario 2: Poster vintage da viaggio (con rendering del testo)
gpt-image-2 è stabile nel layout e nel rendering dei font, ideale per poster, menu, biglietti con testo.
url:

AMALFI e ITALIA 1958 è chiaro e corretto.
Scenario 3: Composizione complessa e conteggio
Questo prompt verifica la capacità del modello di seguire istruzioni strutturate su quantità e posizione.
dall-e-3.
Scenario 4: Stile illustrazione (orizzontale)
Specificando media artistici e parole chiave emotive, si può guidare il modello verso illustrazioni stilizzate.
Asincrono e Callback
gpt-image-2 richiede solitamente 60–90 secondi per chiamata. Se non si vuole mantenere la connessione aperta, si può usare il meccanismo di callback asincrono callback_url descritto più avanti; il flusso è identico agli altri modelli.
Serie di modelli Nano Banana
La serienano-banana è basata sul modello Gemini e integrata tramite la stessa interfaccia /openai/images/generations, senza necessità di cambiare endpoint, basta impostare model su uno dei valori seguenti.
| Modello | Costo (Crediti / chiamata) | Scenario d’uso |
|---|---|---|
nano-banana | 0.14 | Generazione immagini ordinaria, più veloce e a costo più basso |
nano-banana-2 | 0.28 | Qualità e dettagli migliorati |
nano-banana-pro | 0.35 | Modello top di gamma, migliore composizione, dettagli e testo |
Importante: ambito dei parametri supportati Nano Banana è adattato al protocollo OpenAI e supporta solo i parametri:model,prompt,size.
sizeviene mappato internamente inaspect_ratiosecondo la tabella:
1024x1024/512x512/256x256→1:11792x1024→16:91024x1792→9:16- Non supporta
n,quality,style,response_format,background,output_format; se forniti, saranno ignorati.- La struttura di risposta segue il formato OpenAI (
data[].url), macreatedè sempre0, non viene restituitob64_jsonerevised_promptè sempre uguale al prompt originale.
Chiamata base
url:

Aggiornamento al modello flagship nano-banana-pro
Basta cambiare model in nano-banana-pro, gli altri parametri restano uguali:

Callback asincrono
Il meccanismocallback_url è valido anche per nano-banana, il flusso è identico agli altri modelli, vedi la sezione Callback asincrono.
Uso base
Successivamente si può compilare l’interfaccia con i contenuti corrispondenti, come mostrato:
authorization, selezionabile dal menu a tendina; model, che indica il modello OpenAI DALL-E da usare (principalmente uno, dettagli nei modelli forniti); e prompt, la descrizione testuale per generare l’immagine.
Sulla destra si vede il codice di chiamata generato, che si può copiare ed eseguire direttamente o testare cliccando su “Try”.

created: ID univoco della generazione immagine.data: informazioni sul risultato della generazione.
data contiene i dettagli dell’immagine generata; il campo url è il link all’immagine, come mostrato:

Parametro qualità immagine quality
Si può impostare la qualità dell’immagine generata, con due opzioni: standard per immagini standard, hd per immagini con dettagli più fini e maggiore coerenza.
Esempio di impostazione quality a standard:


quality impostato a standard è la seguente:

quality a hd, si ottiene un’immagine con dettagli più fini e maggiore coerenza:

Parametro dimensione immagine size
È possibile impostare la dimensione dell’immagine generata.
Esempio con dimensione 1024x1024:


1024x1024:

1792x1024 si ottiene:
La differenza di dimensioni è evidente. Sono disponibili altre dimensioni, consultare la documentazione ufficiale per dettagli.
Parametro stile immagine style
Il parametro stile ha due opzioni: vivid per immagini più vivide, natural per immagini più naturali.
Esempio con style impostato a vivid:


vivid:

natural:

vivid produce immagini più vivide e realistiche rispetto a natural.
Parametro formato link immagine response_format
Il parametro response_format ha due opzioni: b64_json per codifica Base64 del link immagine, url per link immagine normale visualizzabile direttamente.
Esempio con response_format impostato a url:



response_format impostato a b64_json si ottiene la codifica Base64 dell’immagine:
Callback asincrono
Poiché la generazione immagini può richiedere tempo, mantenere la connessione HTTP aperta può consumare risorse. Per questo l’API supporta callback asincroni. Il flusso è: il client invia la richiesta specificando un campocallback_url; l’API risponde immediatamente con un task_id che identifica il task. Quando il task è completato, il risultato viene inviato in POST JSON all’URL specificato, includendo il task_id per correlare i risultati.
Esempio pratico:
Un webhook è un servizio HTTP che riceve richieste; sostituire con il proprio URL server. Per demo si usa https://webhook.site/, che fornisce un URL pubblico come:
Ad esempio https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Si imposta callback_url a questo URL nel payload:
task_id permette di correlare il risultato con la richiesta.
Gestione errori
In caso di errore, l’API restituisce codici e messaggi di errore, ad esempio:400 token_mismatched: richiesta errata, parametri mancanti o non validi.400 api_not_implemented: richiesta errata, parametri mancanti o non validi.401 invalid_token: non autorizzato, token di autorizzazione mancante o non valido.429 too_many_requests: troppe richieste, superato limite di velocità.500 api_error: errore interno del server.

