Skip to main content
OpenAI Images Generations API supporta attualmente diversi modelli di generazione di immagini, inclusi il classico 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).
Il metodo di chiamata è identico agli altri modelli, basta impostare il campo 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 WIDTHxHEIGHT personalizzato.
Vincoli rigidi upstream per dimensioni personalizzate: larghezza e altezza devono essere multipli di 16, lato lungo ≤ 3840, pixel totali ≤ 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à 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, passando 1024x1024 potresti ricevere 1254x1254, mantenendo la proporzione. Se la dimensione ricevuta viene riutilizzata come size, sarà comunque tariffata come 1K. Le chiamate 4K richiedono solitamente 4–8 minuti; si consiglia di usare il meccanismo di callback asincrono callback_url descritto più avanti.
Riguardo al parametro n gpt-image-2 non supporta n > 1: questo parametro viene ignorato silenziosamente; indipendentemente dal valore di n, 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 variare prompt o seed per evitare immagini troppo simili). Questa limitazione vale anche per gpt-image-1 / gpt-image-1.5 e la serie nano-banana. Solo dall-e-2 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, ecc.) per controllare atmosfera e texture. Esempio di codice Python:
Risultato restituito:
Immagine generata:

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.
Immagine corrispondente al campo url:

Il modello riproduce fedelmente lo stile Art Deco e il testo 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.
Immagine generata:

Il numero di libri (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 può guidare il modello verso illustrazioni stilizzate.
Illustrazione orizzontale generata:

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 serie nano-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.
Importante: ambito dei 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 n, quality, style, response_format, background, output_format; se forniti, saranno 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 il campo url:

Aggiornamento al modello flagship nano-banana-pro

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

Callback asincrono

Il meccanismo callback_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:

Alla prima chiamata è necessario compilare almeno tre campi: 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”.

Esempio di codice Python:
Risultato:
Il risultato contiene vari campi:
  • created: ID univoco della generazione immagine.
  • data: informazioni sul risultato della generazione.
Il campo 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:

Anche qui è disponibile il codice generato a destra, copiabile o testabile con “Try”.

Codice Python di esempio:
Risultato:
L’immagine generata con quality impostato a standard è la seguente:

Con la stessa procedura, 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 con dimensione 1024x1024:

Codice generato a destra disponibile per copia o test:

Codice Python:
Risultato:
Immagine generata con dimensione 1024x1024:

Con dimensione 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:

Codice generato a destra:

Codice Python:
Risultato:
Immagine generata con stile vivid:

Con stile natural:

vivid produce immagini più vivide e realistiche rispetto a natural. 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:

Codice generato a destra:

Codice Python:
Risultato:
Il link immagine è immagine URL e l’immagine è:

Con 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 campo callback_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:
Risposta immediata:
Dopo qualche istante, il webhook riceverà il risultato:
Il campo 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.

Esempio di 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.