Codex : générer des images avec imagegen et un relais

Pour générer des images avec Codex derrière un fournisseur personnalisé (un relais), il suffit de deux lignes dans la config.toml : une entrée http_headers nommée x-openai-actor-authorization avec une valeur non vide, et requires_openai_auth = false, sa valeur par défaut. Codex 0.165.0 envoie alors les requêtes d'image à /images/generations du relais avec le modèle gpt-image-2 et enregistre le PNG dans ~/.codex/generated_images/. Le 29 octobre 2026, nous avons obtenu un PNG de 1024×1024 en 29.0 secondes ; avec la même configuration sans l'en-tête, aucun outil d'image n'apparaissait.

Ces tests ont tourné avec Codex CLI 0.165.0 sur macOS, avec OmniaKey, notre propre passerelle d'API, comme fournisseur personnalisé.

Pourquoi imagegen disparaît avec un fournisseur personnalisé

Codex 0.165.0 décide si le modèle reçoit un outil d'image dans une seule fonction, image_generation_available, à partir du bloc de votre fournisseur et de la session enregistrée.

requires_openai_auth = false sans l'en-tête acteur : aucun outil d'image. Lors de notre essai avec cette configuration, Codex a répondu : "I don’t have a built-in image generation tool available in this session." (Je n'ai pas d'outil de génération d'images intégré disponible dans cette session.)
requires_openai_auth = false plus l'en-tête x-openai-actor-authorization : l'outil apparaît. Nos trois essais avec cet en-tête (une image nouvelle, une retouche et un autocollant transparent) l'ont appelé.
requires_openai_auth = true avec une connexion par clé d'API : aucun outil d'image. Dans le code de Codex 0.165.0, la vérification exige une connexion ChatGPT, et une clé d'API ne compte pas.

Deux conditions plus discrètes se cachent derrière ce filtre, toutes deux dans le code de Codex 0.165.0 : une connexion ChatGPT au forfait gratuit enregistrée masque l'outil même avec un fournisseur personnalisé, et le modèle de chat doit accepter les images, ce que Codex suppose pour les noms de modèles que sa propre liste ne connaît pas.

Quand l'outil manque, Codex indique qu'il n'a pas d'outil d'image intégré, comme dans notre essai sans l'en-tête, ou bien la compétence imagegen propose son repli en ligne de commande, qui a besoin de OPENAI_API_KEY.

La config.toml qui l'active

Ouvrez ~/.codex/config.toml. Dans le bloc de fournisseur de votre relais, ajoutez la ligne http_headers et vérifiez que requires_openai_auth vaut false, sa valeur par défaut.

toml

model = "gpt-6.1-sol"            # un modèle de chat servi par votre relais
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          # déjà actif par défaut dans Codex 0.165.0

model et model_provider sont des clés de premier niveau : elles se placent au-dessus de la première ligne [section], car TOML lit chaque ligne qui suit un en-tête [section] comme faisant partie de cette section.

requires_openai_auth = false garde Codex sur la clé de votre environnement, la variable nommée dans env_key. La page d'authentification d'OpenAI (vérifiée le 29 octobre 2026) indique : "When requires_openai_auth = true, Codex ignores env_key." (Avec requires_openai_auth = true, Codex ignore env_key.)
http_headers contient l'en-tête acteur. La référence de configuration d'OpenAI le décrit comme "Static HTTP headers added to provider requests" (en-têtes HTTP fixes ajoutés aux requêtes du fournisseur), et Codex vérifie seulement que la valeur n'est pas vide (la vérification dans le code de Codex) : "local-relay" est donc un espace réservé, pas un mot de passe.
[features] image_generation = true est facultatif en 0.165.0 : la fonction est stable et active par défaut (codex features list affiche image_generation stable true). Nos essais ne l'ont pas écrite.
wire_api = "responses" est la seule valeur acceptée par la référence de configuration d'OpenAI.

Définissez la clé et lancez Codex :

bash

export RELAY_API_KEY="your-relay-key"
codex

Si Codex tournait déjà, quittez-le et ouvrez une nouvelle session pour qu'il lise la configuration.

Générer une image et retrouver le fichier

Nos essais du 29 octobre 2026 passaient par un fournisseur personnalisé. L'essai 2, la vérification sans l'en-tête, n'a produit aucune image. Les trois autres ont chacun enregistré un PNG 1024×1024. Les durées concernent l'appel d'image, pas le tour complet.

Essai	Notre demande	Appel d'image
1	Une nouvelle icône d'app	29.0 s
3	Retoucher l'image de l'essai 1	37.6 s
4	Un autocollant transparent	19.8 s

L'essai 1 était un seul 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 a ouvert la compétence imagegen de lui-même, sans $imagegen dans le prompt, puis a appelé l'outil. L'appel a duré 29.0 secondes et le tour s'est terminé par un PNG de 1024×1024.

Le fichier arrive dans ~/.codex/generated_images/<session id>/<call id>.png ; ~/.codex est la valeur par défaut de CODEX_HOME. Codex a affiché le chemin parce que le prompt le demandait. Si l'image doit aller dans votre projet, indiquez la destination dans le prompt : la compétence demande alors à Codex de déplacer ou de copier le fichier.

Retoucher une image existante

Le PNG de l'essai 1 est passé dans le dossier de travail sous le nom inkwell.png, et nous avons demandé :

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 a transmis le fichier dans referenced_image_paths, la requête est donc partie vers /images/edits. L'appel a duré 37.6 secondes et le fichier inkwell.png d'origine est resté intact. La page sur la génération d'images d'OpenAI (vérifiée le 29 octobre 2026) précise : "When editing an existing image, say exactly what should change and what must stay the same." (Pour retoucher une image existante, dites exactement ce qui doit changer et ce qui doit rester identique.) Le reste est traité dans le guide de prompts GPT-Image 2.

Nouvelle image

Après une retouche

Les deux images viennent de l'outil d'image intégré de Codex CLI 0.165.0, via un fournisseur personnalisé, le 29 octobre 2026. La retouche ne demandait qu'un nouveau fond ; la plume a gardé sa forme, sa taille et sa position.

Fond transparent

L'essai 4 demandait un autocollant :

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 a réglé transparent_background: true, l'appel a duré 19.8 secondes et 85.0% des pixels du PNG enregistré sont entièrement transparents. La référence de l'Images API d'OpenAI classe les fonds transparents de gpt-image-2 comme "in preview" (en aperçu) : cela a fonctionné lors de notre essai, mais la fonction reste en aperçu.

Essai 4 du 29 octobre 2026 : un PNG à fond transparent, posé sur un damier pour rendre la zone transparente visible. 85.0% de ses pixels sont entièrement transparents.

Ce que votre relais doit renvoyer (gpt-image-2, b64_json)

Codex envoie POST <base_url>/images/generations pour une image nouvelle et POST <base_url>/images/edits pour une retouche, les deux en JSON avec le modèle gpt-image-2, l'identifiant de GPT-Image 2, que votre relais doit servir. La qualité et la taille valent "auto", background vaut "opaque" ou "transparent", et la requête omet response_format et n. Tout part vers la même URL de base, avec la même clé, que vos requêtes de chat. Une retouche transporte l'image source dans le JSON sous forme de data URL, sans téléverser de fichier.

Codex lit une réponse JSON avec created et une liste data dont le premier élément contient b64_json ; les autres champs sont ignorés, comme le montre images.rs. Un échec d'analyse commence par "failed to decode image generation response:".

Vous pouvez tester un relais sans Codex. Enregistrez ceci sous 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]))'

Pointez l'URL de base vers votre relais et exportez votre clé sous RELAY_API_KEY. Le 29 octobre 2026, le contrôle contre notre passerelle a renvoyé HTTP 200 au bout de 25.0 secondes et affiché :

text

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

Si b64_json manque dans cette liste, Codex échoue sur la même réponse. Si le relais renvoie une erreur, le contrôle affiche cette erreur.

Certains relais échouent ici parce qu'ils stockent l'image dans un fichier. La même référence de l'Images API (vérifiée le 29 octobre 2026) qualifie response_format de "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images" (paramètre hérité de format de réponse pour les modèles d'image retirés ; non pris en charge par les modèles d'image GPT, qui renvoient toujours des images encodées en base64), et b64_json est "Returned by default for GPT image models" (renvoyé par défaut pour les modèles d'image GPT). Un relais qui relaie la réponse d'OpenAI telle quelle fonctionne ; celui qui ne renvoie qu'un lien fait échouer Codex.

La passerelle d'OmniaKey a connu ce problème jusqu'à une correction du 29 octobre 2026. La note de correction indique que Codex échouait avec "missing field b64_json" ; la passerelle conserve désormais b64_json, sauf si l'appelant demande une URL.

Si votre relais échoue à ce contrôle, OmniaKey sert gpt-image-2 et des modèles de chat comme gpt-6.1-sol avec une seule clé, et ses réponses d'image contiennent b64_json, comme le montre le contrôle. Placez base_url = "https://api.omniakey.com/v1" dans ce bloc de fournisseur et la clé OmniaKey dans la variable nommée par env_key ; le guide de Codex CLI couvre le reste du fichier, et les tarifs actuels sont sur la page des tarifs.

Erreurs et solutions

Codex dit qu'il n'a pas d'outil d'image

Une des conditions de la première section n'est pas remplie. Ajoutez la ligne http_headers, gardez requires_openai_auth = false avec votre env_key et ouvrez une nouvelle session. Toujours rien ? Lancez codex login status ; avec un forfait ChatGPT gratuit, codex logout supprime la connexion enregistrée et la clé de env_key suffit.

Codex réclame OPENAI_API_KEY

L'outil intégré n'est pas disponible, la compétence imagegen propose donc son repli en ligne de commande, scripts/image_gen.py, qui a besoin de OPENAI_API_KEY. Réparez plutôt l'outil intégré avec la configuration ci-dessus ; en mode intégré, la clé vient de env_key.

failed to decode image generation response: missing field b64_json

Le relais a répondu sans b64_json, le plus souvent avec un lien vers un fichier stocké. Lancez le contrôle de la section sur le relais et envoyez le résultat à l'exploitant ; Codex veut la chaîne base64 dans le premier élément de data.

La requête d'image échoue avec model_not_found

Votre clé n'a pas gpt-image-2 sur ce relais, et Codex envoie toujours cet identifiant, sans réglage pour le changer. Notre passerelle a répondu à un modèle d'image qu'elle ne sert pas par HTTP 503 et le code model_not_found. Utilisez une clé et un relais qui listent gpt-image-2.

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

La requête de chat a été coupée et Codex l'a réessayée ; le compteur indique la tentative sur cinq. Il est apparu une fois dans l'essai 1 ("Concurrency limit exceeded for account, please retry later") et une fois dans l'essai 3 (une erreur de transport), et les deux essais ont abouti après la nouvelle tentative. S'il revient, vérifiez les limites du relais ; les soucis de chat sont traités dans le kit de compatibilité Codex.

Questions fréquentes

Faut-il OPENAI_API_KEY pour imagegen ?

Non. En mode intégré, la clé vient de la variable nommée dans env_key ; seul le repli en ligne de commande de la compétence lit OPENAI_API_KEY.

Peut-on choisir un autre modèle d'image, une autre taille ou qualité ?

Pas dans Codex 0.165.0. L'outil envoie gpt-image-2 avec la qualité et la taille "auto", config.toml n'a aucune clé pour cela et toutes les images de nos essais sont revenues en 1024×1024. Pour une autre taille ou un autre modèle, appelez directement le point d'accès d'images de votre relais.

Faut-il taper $imagegen ?

Non. Lors de nos essais, Codex a ouvert la compétence imagegen de lui-même. La documentation d'OpenAI indique que $imagegen dans le prompt appelle la compétence explicitement, ce qui aide quand Codex ne la choisit pas.

Cela fonctionne-t-il dans l'application de bureau Codex ?

Nous n'avons pas testé l'application de bureau, seulement la CLI. Le dépôt de correctifs communautaire indique qu'un Codex Desktop en cours d'exécution ne prend pas les nouvelles variables d'environnement : son script macOS installe un LaunchAgent, puis vous quittez complètement Codex et ouvrez une nouvelle tâche.

Sources vérifiées

Créer une clé d'API OmniaKey Voir GPT-Image 2