Skip to main content
OpenAI Images Generations API supporta attualmente diversi modelli di generazione di immagini, inclusi i classici 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).
Il metodo di chiamata è identico agli altri modelli, basta impostare il campo 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 passare size: "auto" o omettere il campo size, 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, inviando 1024x1024 potresti ricevere 1254x1254, mantenendo però la proporzione. Se lo reinvi come size, la tariffazione rimane invariata. La generazione 4K richiede generalmente 4–8 minuti per chiamata; si consiglia di usare il meccanismo di callback asincrono callback_url descritto più avanti.
Nota sul parametro n gpt-image-2 attualmente non supporta n > 1: questo parametro viene ignorato silenziosamente, indipendentemente dal valore (ad esempio n=1 o n=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 per gpt-image-1 / gpt-image-1.5 e la serie nano-banana. dall-e-2 è l’unico modello che supporta nativamente n > 1; dall-e-3 supporta solo n = 1.
Di seguito alcuni esempi reali per mostrare le capacità di 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:
Risultato restituito:
Immagine generata:

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.
Immagine corrispondente all’URL nel risultato:

Il modello riproduce fedelmente lo stile Art Deco e rende chiaramente i testi 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.
Immagine generata:

Si nota che il numero di libri su ogni ripiano (1 / 3 / 7) corrisponde esattamente al prompt, cosa difficile da ottenere stabilmente con dall-e-3.

Scenario 4: Stile illustrazione (orizzontale)

Specificando media artistici e parole chiave emotive, si ottengono illustrazioni stilizzate.
Illustrazione orizzontale generata:

Asincrono e Callback

La generazione con gpt-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 serie nano-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.
  • size viene mappato internamente in aspect_ratio secondo la tabella:
    • 1024x1024 / 512x512 / 256x2561:1
    • 1792x102416:9
    • 1024x17929: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), ma created è sempre 0, non viene restituito b64_json e revised_prompt è sempre uguale al prompt originale.

Chiamata base

Risultato:
L’immagine generata è accessibile direttamente tramite l’URL restituito:

Upgrade al modello top nano-banana-pro

Basta cambiare model in nano-banana-pro, mantenendo gli altri parametri identici:
Esempio di risposta:

Callback asincrono

Il meccanismo di callback asincrono callback_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:
Risultato:
Il risultato contiene vari campi:
  • created: ID univoco della generazione immagine.
  • data: informazioni sul risultato della generazione.
Nel campo 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.
Esempio di impostazione quality a standard:

A destra si vede il codice generato, copiabile o testabile con «Try».

Esempio Python:
Risultato:
L’immagine generata con 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:
Risultato:
Immagine generata a 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.
Esempio impostazione stile a vivid:

Codice generato a destra:

Esempio Python:
Risultato:
Immagine generata con stile vivid:

Impostando stile a natural si ottiene:

vivid produce immagini più vivide rispetto a natural. Il parametro response_format può essere:
  • b64_json: codifica Base64 del contenuto immagine.
  • url: link diretto all’immagine.
Esempio impostazione a url:

Codice generato a destra:

Esempio Python:
Risultato:
Il link all’immagine è accessibile direttamente: Immagine URL Immagine:

Impostando 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 campo callback_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:
Risposta immediata:
Dopo qualche istante, sul webhook vedrai il risultato:
Il campo 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.

Esempio risposta errore

Conclusione

Con questo documento hai appreso come utilizzare OpenAI Images Generations API per sfruttare facilmente la generazione immagini ufficiale OpenAI DALL-E. Speriamo che questa guida ti aiuti a integrare e utilizzare al meglio l’API. Per qualsiasi domanda, contatta il nostro team di supporto tecnico.