dall-e-3, il modello con capacità di rendering testuale più avanzata gpt-image-1, la generazione più recente 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 illustra principalmente il processo di utilizzo dell’API OpenAI Images Generations, che consente di sfruttare 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 le istruzioni: comprende accuratamente istruzioni strutturate complesse come composizione, conteggio, relazioni spaziali.
- Rendering testuale più nitido: in scenari come poster, menu, infografiche, loghi, i testi in inglese e i numeri sono quasi privi di errori.
- Espressione stilistica più ricca: supporta nativamente diversi stili come ritratti cinematografici, poster vintage, illustrazioni per bambini, fotografia di prodotto, infografiche.
- 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 nel risultato è un link permanente ospitato su platform.cdn.acedata.cloud, che può essere aperto direttamente nel browser o incorporato in pagine web.
Valori supportati per size
gpt-image-2 verifica solo il formato di size: purché non sia auto o stringa vuota, deve corrispondere al formato WIDTHxHEIGHT (es. 1024x1024, 2048x1152, 800x600); qualsiasi altro formato restituirà errore 400. Tutte le dimensioni (1K / 2K / 4K / personalizzate) sono tariffate uniformemente per immagine, senza sovrapprezzo per dimensione.
Vincoli rigidi a monte per dimensioni personalizzate: larghezza e altezza devono essere multipli di 16, lato lungo ≤ 3840, numero totale di pixel ≤ 8.294.400. Dimensioni fuori da questi limiti saranno rifiutate con errore 4xx.
Puoi anche passaresize: "auto"o omettere il camposize, in tal caso il modello sceglierà automaticamente la dimensione predefinita. Per il livello 1K, l’output a monte non garantisce un allineamento pixel perfetto — ad esempio, inviando1024x1024potresti ricevere1254x1254, mantenendo però la proporzione. Se lo reinvi comesize, la tariffazione rimane invariata. La generazione 4K richiede generalmente 4–8 minuti per chiamata; si consiglia di usare il meccanismo di callback asincronocallback_urldescritto più avanti.
Nota sul parametroDi seguito alcuni esempi reali per mostrare le capacità dingpt-image-2attualmente non supportan > 1: questo parametro viene ignorato silenziosamente, indipendentemente dal valore (ad esempion=1on=10), ogni richiesta restituisce solo 1 immagine e viene tariffata come 1 immagine. Se vuoi ottenere più immagini candidate contemporaneamente, devi effettuare più richieste in parallelo (consigliato passare prompt o seed diversi per evitare immagini troppo simili). Questa limitazione vale anche pergpt-image-1/gpt-image-1.5e la serienano-banana.dall-e-2è l’unico modello che supporta 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) per controllare atmosfera e texture. Esempio di chiamata Python:Scenario 2: Poster vintage da viaggio (con rendering testo)
gpt-image-2 è stabile nel layout e nel rendering dei font, ideale per poster, menu, biglietti con testo.
AMALFI e ITALIA 1958.
Scenario 3: Composizione complessa e conteggio
Il prompt seguente testa la capacità del modello di seguire istruzioni strutturate su quantità e posizionamento.dall-e-3.
Scenario 4: Stile illustrazione (orizzontale)
Specificando media artistici e parole chiave emotive, si ottengono illustrazioni stilizzate.Asincrono e Callback
La generazione congpt-image-2 richiede generalmente 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; la procedura è identica agli altri modelli.
Modelli della serie Nano Banana
La serienano-banana è basata su Gemini e integrata tramite la stessa interfaccia /openai/images/generations, senza bisogno di cambiare endpoint; basta impostare model su uno dei modelli della tabella seguente.
Importante: 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 parametri come
n,quality,style,response_format,background,output_format; se presenti vengono 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
Upgrade al modello top nano-banana-pro
Basta cambiare model in nano-banana-pro, mantenendo gli altri parametri identici:
Callback asincrono
Il meccanismo di callback asincronocallback_url funziona anche per nano-banana, con procedura identica agli altri modelli (vedi sezione Asincrono e Callback).
Uso base
Ora puoi compilare i campi corrispondenti nell’interfaccia, come mostrato: Al primo utilizzo dell’API, devi compilare almeno tre campi:authorization, selezionabile dal menu a tendina; model, che indica il modello OpenAI DALL-E da usare (principalmente uno, vedi modelli disponibili); infine prompt, la descrizione testuale per generare l’immagine.
A destra puoi vedere il codice di chiamata generato, che puoi copiare ed eseguire direttamente oppure testare cliccando su «Try».
Esempio di chiamata Python:
created: ID univoco della generazione immagine.data: informazioni sul risultato della generazione.
data si trova l’URL dell’immagine generata, come mostrato:
Parametro qualità immagine quality
Ora vediamo come impostare parametri dettagliati per la generazione, tra cui la qualità dell’immagine quality che può essere:
standard: immagine generata standard.hd: immagine con dettagli più fini e maggiore coerenza.
quality a standard:
A destra si vede il codice generato, copiabile o testabile con «Try».
Esempio Python:
quality impostato a standard:
Impostando 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 impostazione dimensione a 1024x1024:
Codice generato a destra, copiabile o testabile:
Esempio Python:
1024x1024:
Impostando dimensione a 1792x1024 si ottiene:
Le dimensioni sono chiaramente diverse. Sono disponibili altre dimensioni, consultare la documentazione ufficiale per dettagli.
Parametro stile immagine style
Il parametro stile può essere:
vivid: immagine più vivida e intensa.natural: immagine più naturale.
vivid:
Codice generato a destra:
Esempio Python:
vivid:
Impostando stile a natural si ottiene:
vivid produce immagini più vivide rispetto a natural.
Parametro formato link immagine response_format
Il parametro response_format può essere:
b64_json: codifica Base64 del contenuto immagine.url: link diretto all’immagine.
url:
Codice generato a destra:
Esempio Python:
response_format a b64_json si ottiene la codifica Base64:
Callback asincrono
Poiché la generazione immagini con OpenAI Images Generations API può richiedere tempo, mantenere la connessione HTTP aperta per molto tempo consuma risorse di sistema. Per questo l’API supporta callback asincroni. Il flusso è: il client invia la richiesta specificando il campocallback_url; l’API risponde immediatamente con un task_id che identifica il task. Quando la generazione è completata, il risultato viene inviato tramite POST JSON all’URL callback_url specificato, includendo anche il task_id per correlare i risultati.
Esempio pratico:
Il webhook è un servizio HTTP che riceve richieste; devi sostituire l’URL con il tuo server. Per prova, puoi usare il sito pubblico https://webhook.site/ che genera un URL webhook, come mostrato:
Copia l’URL, ad esempio https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab.
Imposta callback_url nel payload:
task_id consente di correlare la risposta asincrona con la richiesta.
Gestione errori
In caso di errore, l’API restituisce un codice e un messaggio 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: autorizzazione mancante o token non valido.429 too_many_requests: troppe richieste, superato il limite di velocità.500 api_error: errore interno del server.

