Codex: generare immagini con imagegen e un provider custom

Per generare immagini con Codex attraverso un provider custom (relay) bastano due righe nel config.toml: una voce http_headers chiamata x-openai-actor-authorization con un valore qualsiasi non vuoto, e requires_openai_auth = false, che è già il valore predefinito. Così Codex 0.165.0 manda le richieste immagine a /images/generations del relay con il modello gpt-image-2 e salva il PNG in ~/.codex/generated_images/. Il 29 ottobre 2026 abbiamo ottenuto un PNG 1024×1024 in 29.0 secondi; con la stessa configurazione senza quell'header, nessun tool immagine compariva.

Abbiamo provato tutto con Codex CLI 0.165.0 su macOS, usando OmniaKey, il nostro gateway API, come provider custom.

Perché imagegen sparisce con un provider custom

Codex 0.165.0 decide se il modello riceve un tool immagini in un'unica funzione, image_generation_available, partendo dal blocco del provider e dal login salvato.

requires_openai_auth = false senza l'header attore: nessun tool immagini. Nella nostra prova con questa configurazione Codex ha risposto: "I don’t have a built-in image generation tool available in this session." (Non ho un tool di generazione immagini integrato disponibile in questa sessione.)
requires_openai_auth = false più l'header x-openai-actor-authorization: il tool compare. Tutte e tre le nostre prove con l'header (una immagine nuova, una modifica e uno sticker trasparente) hanno chiamato il tool.
requires_openai_auth = true con login tramite chiave API: nessun tool immagini. Nel codice di Codex 0.165.0 quel controllo richiede un login ChatGPT, e una chiave API non vale.

Dietro quel filtro ci sono due condizioni minori, entrambe nel codice di Codex 0.165.0: un login al piano gratuito di ChatGPT nasconde il tool anche con un provider custom, e il modello di chat deve accettare immagini, cosa che Codex dà per scontata con nomi di modello che la sua lista non conosce.

Quando il tool manca, Codex dice che non ha un tool immagini integrato, come nella nostra prova senza header, oppure la skill imagegen propone la scorciatoia da CLI, che richiede OPENAI_API_KEY.

Il config.toml che lo attiva

Apri ~/.codex/config.toml. Nel blocco del provider del tuo relay aggiungi la riga http_headers e verifica che requires_openai_auth sia su false, il valore predefinito.

toml

model = "gpt-6.1-sol"            # un modello di chat servito dal tuo relay
model_provider = "relay"

[model_providers.relay]
name = "My relay"
base_url = "https://api.omniakey.com/v1"
env_key = "RELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "local-relay" }

[features]
image_generation = true          # su Codex 0.165.0 è già attivo per impostazione predefinita

model e model_provider sono chiavi di primo livello, quindi vanno sopra la prima riga [section]: TOML legge ogni riga dopo un'intestazione [section] come parte di quella sezione.

requires_openai_auth = false lascia che Codex usi la chiave del tuo ambiente, cioè la variabile indicata in env_key. La pagina sull'autenticazione di OpenAI (controllata il 29 ottobre 2026) dice: "When requires_openai_auth = true, Codex ignores env_key." (Con requires_openai_auth = true Codex ignora env_key.)
http_headers contiene l'header attore. La referenza di configurazione di OpenAI lo chiama "Static HTTP headers added to provider requests" (header HTTP statici aggiunti alle richieste al provider), e Codex controlla solo che il valore non sia vuoto (il controllo nel codice di Codex), quindi "local-relay" è un segnaposto, non una password.
[features] image_generation = true è facoltativo su 0.165.0, dove la funzione è stabile e attiva per impostazione predefinita (codex features list stampa image_generation stable true). Nelle nostre prove non abbiamo scritto quella riga.
wire_api = "responses" è l'unico valore accettato dalla referenza di configurazione di OpenAI.

Imposta la chiave e avvia Codex:

bash

export RELAY_API_KEY="your-relay-key"
codex

Se Codex era già in esecuzione, chiudilo e apri una sessione nuova, così legge la configurazione.

Genera un'immagine e trova il file

Le nostre prove del 29 ottobre 2026 sono passate da un provider custom. La prova 2, il controllo senza l'header, non ha prodotto nessuna immagine. Le altre tre hanno salvato ciascuna un PNG 1024×1024. I tempi riguardano la chiamata immagine, non l'intero turno.

Prova	Cosa abbiamo chiesto	Chiamata immagine
1	Una nuova icona per un'app	29.0 s
3	Modificare l'immagine della prova 1	37.6 s
4	Uno sticker trasparente	19.8 s

La prova 1 era un solo prompt:

Create an app icon for a note-taking app called Inkwell: a fountain pen nib over a deep blue gradient, flat vector style, no text. Generate it with your image tool, then tell me where the file was saved.

Codex ha aperto da solo la skill imagegen, senza $imagegen nel prompt, e poi ha chiamato il tool. La chiamata è durata 29.0 secondi e il turno si è chiuso con un PNG 1024×1024.

Il file finisce in ~/.codex/generated_images/<session id>/<call id>.png; ~/.codex è il valore predefinito di CODEX_HOME. Codex ha stampato il percorso perché il prompt lo chiedeva. Se l'immagine serve nel tuo progetto, indica la destinazione nel prompt: la skill dice a Codex di spostare o copiare lì il file.

Modificare un'immagine esistente

Il PNG della prova 1 è finito nella cartella di lavoro come inkwell.png, e abbiamo chiesto:

Edit the image ./inkwell.png: change the background to a warm orange gradient and keep the pen nib as it is. Use your built-in image tool, then tell me where the edited file was saved.

Codex ha passato il file in referenced_image_paths, quindi la richiesta è andata a /images/edits. La chiamata è durata 37.6 secondi e l'inkwell.png originale è rimasto com'era. La pagina sulla generazione di immagini di OpenAI (controllata il 29 ottobre 2026) dice: "When editing an existing image, say exactly what should change and what must stay the same." (Quando modifichi un'immagine esistente, indica esattamente cosa deve cambiare e cosa deve restare uguale.) Il resto è nella guida ai prompt di GPT-Image 2.

Immagine nuova

Dopo una modifica

Entrambe le immagini sono uscite dal tool immagini integrato di Codex CLI 0.165.0, tramite provider custom, il 29 ottobre 2026. La modifica chiedeva solo uno sfondo nuovo; la punta ha mantenuto forma, dimensione e posizione.

Sfondo trasparente

La prova 4 chiedeva uno sticker:

Create a PNG sticker of a single fountain pen nib on a fully transparent background (no backdrop at all), flat vector style, no text. Generate it with your built-in image tool, then tell me where the file was saved.

Codex ha impostato transparent_background: true, la chiamata è durata 19.8 secondi e l'85.0% dei pixel del PNG salvato è completamente trasparente. La referenza delle Images API di OpenAI elenca gli sfondi trasparenti per gpt-image-2 come "in preview" (in anteprima): nella nostra prova ha funzionato, ma la funzione resta in anteprima.

Prova 4 del 29 ottobre 2026: un PNG con sfondo trasparente, mostrato su una scacchiera perché l'area trasparente si veda. L'85.0% dei pixel è completamente trasparente.

Cosa deve restituire il tuo relay (gpt-image-2, b64_json)

Codex invia POST <base_url>/images/generations per una immagine nuova e POST <base_url>/images/edits per una modifica, entrambe in JSON con il modello gpt-image-2, l'id di GPT-Image 2 che il tuo relay deve servire. Qualità e dimensione vanno come "auto", background va come "opaque" o "transparent", e la richiesta lascia fuori response_format e n. Tutto passa dallo stesso URL di base e dalla stessa chiave delle richieste di chat. Una modifica porta l'immagine di partenza dentro il JSON come data URL, invece di caricare un file.

Codex legge una risposta JSON con created e una lista data il cui primo elemento contiene b64_json; gli altri campi sono ignorati, come mostra images.rs. Un errore di lettura comincia con "failed to decode image generation response:".

Puoi controllare un relay senza Codex. Salva questo come relay-check.sh:

bash

curl -s https://api.omniakey.com/v1/images/generations \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "a red apple on a white table", "background": "opaque", "quality": "auto", "size": "auto"}' \
  | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("error") or sorted(r["data"][0]))'

Punta l'URL di base al tuo relay ed esporta la chiave come RELAY_API_KEY. Il 29 ottobre 2026 il controllo verso il nostro gateway ha restituito HTTP 200 in 25.0 secondi e ha stampato:

text

['asset_id', 'b64_json', 'expires_at', 'revised_prompt', 'url']

Se b64_json manca da quella lista, Codex fallisce sulla stessa risposta. Se il relay restituisce un errore, il controllo stampa quell'errore.

Alcuni relay si rompono qui perché salvano l'immagine come file. La stessa referenza delle Images API (controllata il 29 ottobre 2026) chiama response_format "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (parametro legacy del formato di risposta per i modelli immagine ritirati; non supportato dai modelli immagine GPT, che restituiscono sempre immagini codificate in base64), e b64_json "Returned by default for GPT image models" (restituito per impostazione predefinita dai modelli immagine GPT). Un relay che inoltra la risposta di OpenAI senza modificarla funziona; uno che restituisce solo un link rompe Codex.

Il gateway OmniaKey ha avuto questo problema fino a una correzione del 29 ottobre 2026. La nota della correzione dice che Codex falliva con "missing field b64_json", e ora il gateway tiene b64_json a meno che chi chiama non chieda un URL.

Se il tuo relay non passa il controllo, OmniaKey serve gpt-image-2 e modelli di chat come gpt-6.1-sol con una sola chiave, e le risposte immagine includono b64_json, come mostra il controllo. Metti base_url = "https://api.omniakey.com/v1" in quel blocco del provider e la chiave OmniaKey nella variabile indicata da env_key; il resto del file è nella guida a Codex CLI, e i prezzi attuali sono nella pagina dei prezzi.

Errori e soluzioni

Codex dice che non ha un tool immagini

Una delle condizioni della prima sezione non è soddisfatta. Aggiungi la riga http_headers, lascia requires_openai_auth = false con il tuo env_key e apri una sessione nuova. Non cambia nulla? Lancia codex login status; con un piano gratuito di ChatGPT, codex logout cancella il login salvato e la chiave di env_key basta.

Codex chiede OPENAI_API_KEY

Il tool integrato non è disponibile, quindi la skill imagegen propone la scorciatoia da CLI, scripts/image_gen.py, che richiede OPENAI_API_KEY. Sistema il tool integrato con la configurazione qui sopra; in modalità integrata la chiave arriva da env_key.

failed to decode image generation response: missing field b64_json

Il relay ha risposto senza b64_json, quasi sempre con un link a un file salvato. Lancia il controllo della sezione sul relay e passa il risultato a chi lo gestisce; Codex vuole la stringa base64 nel primo elemento di data.

La richiesta immagine fallisce con model_not_found

La tua chiave non ha gpt-image-2 su quel relay, e Codex manda sempre quell'id, senza impostazioni per cambiarlo. Il nostro gateway ha risposto a un modello immagine che non serve con HTTP 503 e il codice model_not_found. Usa una chiave e un relay che elencano gpt-image-2.

Reconnecting... 1/5 (stream disconnected before completion)

La richiesta di chat è caduta e Codex ha riprovato; il contatore mostra il tentativo su cinque. È comparso una volta nella prova 1 ("Concurrency limit exceeded for account, please retry later") e una volta nella prova 3 (un errore di trasporto), e entrambe le prove sono terminate dopo il nuovo tentativo. Se torna sempre, controlla i limiti del relay; i problemi di chat sono nel kit di compatibilità per Codex.

Domande frequenti

Serve OPENAI_API_KEY per imagegen?

No. In modalità integrata la chiave arriva dalla variabile indicata in env_key; solo la scorciatoia da CLI della skill legge OPENAI_API_KEY.

Posso scegliere un altro modello immagine, una dimensione o una qualità?

Su Codex 0.165.0 no. Il tool manda gpt-image-2 con qualità e dimensione "auto", il config.toml non ha chiavi per questo e tutte le immagini delle nostre prove sono arrivate in 1024×1024. Per un'altra dimensione o un altro modello, chiama direttamente l'endpoint immagini del tuo relay.

Devo scrivere $imagegen?

No. Nelle nostre prove Codex apriva da solo la skill imagegen. La documentazione di OpenAI dice che $imagegen nel prompt chiama la skill in modo esplicito, e questo aiuta quando Codex non la sceglie.

Funziona nell'app desktop di Codex?

Non abbiamo provato l'app desktop, solo la CLI. La repository della correzione della community dice che un Codex Desktop in esecuzione non prende le nuove variabili d'ambiente: lo script per macOS installa un LaunchAgent, poi chiudi del tutto Codex e apri un'attività nuova.

Fonti consultate

Crea una chiave API OmniaKey Scopri GPT-Image 2