Codex: generar imágenes con proveedor personalizado e imagegen

Para generar imágenes con Codex a través de un proveedor personalizado (relay) hace falta una línea en el bloque del proveedor: un http_headers llamado x-openai-actor-authorization con cualquier valor no vacío, y requires_openai_auth = false, que es su valor por defecto. Con eso, Codex 0.165.0 envía las peticiones de imagen a /images/generations del relay con el modelo gpt-image-2 y guarda el PNG en ~/.codex/generated_images/. El 29 de octubre de 2026 obtuvimos un PNG de 1024×1024 en 29.0 segundos; con la misma configuración sin la cabecera no aparecía la herramienta de imagen.

Hicimos estas pruebas con Codex CLI 0.165.0 en macOS y usamos OmniaKey, nuestra propia pasarela de API, como proveedor personalizado.

Por qué imagegen desaparece con un proveedor personalizado

Codex 0.165.0 decide si el modelo recibe una herramienta de imagen en una sola función, image_generation_available, a partir del bloque de tu proveedor y del inicio de sesión que tiene guardado.

requires_openai_auth = false sin la cabecera de actor: no hay herramienta de imagen. En nuestra prueba con esa configuración, Codex respondió: "I don’t have a built-in image generation tool available in this session." (No tengo una herramienta de generación de imágenes integrada disponible en esta sesión.)
requires_openai_auth = false más la cabecera x-openai-actor-authorization: la herramienta aparece. Nuestras tres ejecuciones con ella (una imagen nueva, una edición y una pegatina transparente) la llamaron.
requires_openai_auth = true con inicio de sesión por clave de API: no hay herramienta de imagen. Según el código de Codex 0.165.0, la comprobación pide un inicio de sesión de ChatGPT, y una clave de API no cuenta.

Detrás de esa puerta hay dos condiciones menores, ambas en el código de Codex 0.165.0: un plan gratuito de ChatGPT guardado esconde la herramienta incluso con un proveedor personalizado, y el modelo de chat tiene que aceptar imágenes, algo que Codex da por hecho con los nombres de modelo que su propia lista no conoce.

Cuando la herramienta falta, Codex dice que no tiene herramienta de imagen integrada, como en nuestra prueba sin la cabecera, o la skill imagegen ofrece su alternativa por CLI, que necesita OPENAI_API_KEY.

El config.toml que la activa

Abre ~/.codex/config.toml. En el bloque del proveedor de tu relay, añade la línea http_headers y comprueba que requires_openai_auth sea false, su valor por defecto.

toml

model = "gpt-6.1-sol"            # un modelo de chat que sirve tu 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          # ya viene activada por defecto en Codex 0.165.0

model y model_provider son claves de primer nivel, así que van encima de la primera línea [section]: TOML lee todas las líneas que siguen a una cabecera [section] como parte de esa sección.

requires_openai_auth = false mantiene a Codex con la clave de tu entorno, la variable que indica env_key. La página de autenticación de OpenAI (consultada el 29 de octubre de 2026) dice: "When requires_openai_auth = true, Codex ignores env_key." (Con requires_openai_auth = true, Codex ignora env_key.)
http_headers contiene la cabecera de actor. La referencia de configuración de OpenAI la llama "Static HTTP headers added to provider requests" (cabeceras HTTP fijas que se añaden a las peticiones del proveedor), y Codex solo comprueba que el valor no esté vacío (la comprobación en el código de Codex), así que "local-relay" es un marcador de posición, no una contraseña.
[features] image_generation = true es opcional en 0.165.0, donde la función es estable y viene activada por defecto (codex features list imprime image_generation stable true). En nuestras ejecuciones no la escribimos.
wire_api = "responses" es el único valor que admite la referencia de configuración de OpenAI.

Configura la clave y arranca Codex:

bash

export RELAY_API_KEY="your-relay-key"
codex

Si Codex ya estaba en marcha, ciérralo y abre una sesión nueva para que lea la configuración.

Genera una imagen y encuentra el archivo

Nuestras ejecuciones del 29 de octubre de 2026 pasaron por un proveedor personalizado. La ejecución 2, la comprobación sin la cabecera, no generó ninguna imagen. Las otras tres guardaron un PNG de 1024×1024 cada una. Los tiempos son de la llamada de imagen, no del turno completo.

Ejecución	Qué pedimos	Llamada de imagen
1	Un icono de app nuevo	29.0 s
3	Editar la imagen de la ejecución 1	37.6 s
4	Una pegatina transparente	19.8 s

La ejecución 1 fue 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 abrió la skill imagegen por su cuenta, sin $imagegen en el prompt, y después llamó a la herramienta. La llamada tardó 29.0 segundos y el turno terminó con un PNG de 1024×1024.

El archivo queda en ~/.codex/generated_images/<session id>/<call id>.png; ~/.codex es el CODEX_HOME por defecto. Codex imprimió la ubicación porque el prompt se lo pedía. Si la imagen va a tu proyecto, indica el destino en el prompt y la skill le dice a Codex que mueva o copie el archivo allí.

Editar una imagen existente

El PNG de la ejecución 1 pasó a la carpeta de trabajo como inkwell.png, y pedimos:

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 pasó el archivo en referenced_image_paths, así que la petición fue a /images/edits. La llamada tardó 37.6 segundos y el inkwell.png original quedó como estaba. La página de generación de imágenes de OpenAI (consultada el 29 de octubre de 2026) dice: "When editing an existing image, say exactly what should change and what must stay the same." (Al editar una imagen existente, di exactamente qué debe cambiar y qué debe quedarse igual.) El resto lo cubre la guía de prompts de GPT-Image 2.

Imagen nueva

Después de una edición

Las dos imágenes salieron de la herramienta de imagen integrada de Codex CLI 0.165.0 a través de un proveedor personalizado el 29 de octubre de 2026. La edición solo pedía un fondo nuevo; el plumín conservó forma, tamaño y posición.

Fondo transparente

La ejecución 4 pidió una pegatina:

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 puso transparent_background: true, la llamada tardó 19.8 segundos y el 85.0% de los píxeles del PNG guardado son totalmente transparentes. La referencia de la Images API de OpenAI lista los fondos transparentes de gpt-image-2 como "in preview" (en vista previa): funcionó en nuestra ejecución, pero sigue siendo una función en vista previa.

Ejecución 4 del 29 de octubre de 2026: un PNG con fondo transparente, mostrado sobre un tablero de ajedrez para que se vea la zona transparente. El 85.0% de sus píxeles son totalmente transparentes.

Qué tiene que devolver tu relay (gpt-image-2, b64_json)

Codex envía POST <base_url>/images/generations para una imagen nueva y POST <base_url>/images/edits para una edición, ambos en JSON con el modelo gpt-image-2, el id de GPT-Image 2, que tu relay tiene que servir. La calidad y el tamaño van en "auto", background va en "opaque" o "transparent", y la petición omite response_format y n. Todo va a la misma URL base, con la misma clave, que tus peticiones de chat. Una edición lleva la imagen de origen dentro del JSON como data URL en lugar de subir un archivo.

Codex lee una respuesta JSON con created y una lista data cuyo primer elemento contiene b64_json; el resto de campos se ignoran, como muestra images.rs. Un fallo de análisis empieza por "failed to decode image generation response:".

Puedes comprobar un relay sin Codex. Guarda esto como 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]))'

Apunta la URL base a tu relay y exporta tu clave como RELAY_API_KEY. El 29 de octubre de 2026 la comprobación contra nuestra pasarela devolvió HTTP 200 a los 25.0 segundos e imprimió:

text

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

Si b64_json falta en esa lista, Codex falla con la misma respuesta. Si el relay devuelve un error, la comprobación imprime ese error.

Algunos relays fallan aquí porque guardan la imagen como archivo. La misma referencia de la Images API (consultada el 29 de octubre de 2026) dice que response_format es un "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (parámetro heredado de formato de respuesta para modelos de imagen retirados; no es compatible con los modelos GPT de imagen, que siempre devuelven imágenes en base64), y que b64_json es "Returned by default for GPT image models" (se devuelve por defecto en los modelos GPT de imagen). Un relay que reenvía la respuesta de OpenAI tal cual funciona; uno que solo devuelve un enlace rompe Codex.

La pasarela de OmniaKey tuvo ese problema hasta una corrección del 29 de octubre de 2026. La nota de la corrección dice que Codex fallaba con "missing field b64_json", y ahora la pasarela conserva b64_json salvo que quien llama pida una URL.

Si tu relay no pasa la comprobación, OmniaKey sirve gpt-image-2 y modelos de chat como gpt-6.1-sol con una sola clave, y sus respuestas de imagen incluyen b64_json, como muestra la comprobación. Pon base_url = "https://api.omniakey.com/v1" en ese bloque del proveedor y la clave de OmniaKey en la variable que nombra env_key; la guía de Codex CLI cubre el resto del archivo, y las tarifas actuales están en la página de precios.

Errores y soluciones

Codex dice que no tiene herramienta de imagen

No se cumple una de las condiciones de la primera sección. Añade la línea http_headers, mantén requires_openai_auth = false con tu env_key y abre una sesión nueva. ¿Sigue igual? Ejecuta codex login status; con un plan gratuito de ChatGPT, codex logout borra el inicio de sesión guardado y basta con la clave de env_key.

Codex pide OPENAI_API_KEY

La herramienta integrada no está disponible, así que la skill imagegen ofrece su alternativa por CLI, scripts/image_gen.py, que necesita OPENAI_API_KEY. Arregla la herramienta integrada con la configuración de arriba; en modo integrado la clave sale de env_key.

failed to decode image generation response: missing field b64_json

El relay respondió sin b64_json, normalmente con un enlace a un archivo guardado. Ejecuta la comprobación de la sección del relay contra él y manda el resultado a quien lo opera; Codex quiere la cadena base64 en el primer elemento de data.

La petición de imagen falla con model_not_found

Tu clave no tiene gpt-image-2 en este relay, y Codex siempre envía ese id, sin ajuste para cambiarlo. Nuestra pasarela respondió a un modelo de imagen que no sirve con HTTP 503 y el código model_not_found. Usa una clave y un relay que listen gpt-image-2.

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

La petición de chat se cortó y Codex la reintentó; el contador muestra el intento de cinco. Apareció una vez en la ejecución 1 ("Concurrency limit exceeded for account, please retry later") y otra en la ejecución 3 (un error de transporte), y ambas terminaron tras el reintento. Si se repite, revisa los límites del relay; el kit de compatibilidad de Codex cubre los problemas de chat.

Preguntas frecuentes

¿Necesito OPENAI_API_KEY para imagegen?

No. En modo integrado la clave sale de la variable que indica env_key; solo la alternativa por CLI de la skill lee OPENAI_API_KEY.

¿Puedo elegir otro modelo de imagen, tamaño o calidad?

En Codex 0.165.0 no. La herramienta envía gpt-image-2 con calidad y tamaño "auto", config.toml no tiene ninguna clave para eso y todas las imágenes de nuestras ejecuciones llegaron en 1024×1024. Para otro tamaño o modelo, llama directamente al endpoint de imágenes de tu relay.

¿Tengo que escribir $imagegen?

No. En nuestras ejecuciones Codex abrió la skill imagegen por su cuenta. La documentación de OpenAI dice que $imagegen en el prompt invoca la skill de forma explícita, lo que ayuda cuando Codex no la elige.

¿Funciona en la app de escritorio de Codex?

No probamos la app de escritorio, solo la CLI. El repositorio de la corrección de la comunidad dice que un Codex Desktop en marcha no toma las variables de entorno nuevas: su script para macOS instala un LaunchAgent, y después cierras Codex del todo y abres una tarea nueva.

Fuentes consultadas

Crea una clave de API de OmniaKey Ver GPT-Image 2