Codex 画像生成：カスタムプロバイダーで imagegen を使う

Codex 画像生成をカスタムプロバイダー（中継サーバー）で使うには、Codex 0.165.0 のプロバイダー設定に x-openai-actor-authorization という名前の http_headers を 1 行足し、値を空でないものにします。requires_openai_auth = false は既定値のままにします。これで Codex は画像リクエストを中継サーバーの /images/generations にモデル gpt-image-2 で送り、PNG を ~/.codex/generated_images/ に保存します。2026 年 10 月 29 日は 1024×1024 の PNG が 29.0 秒で返りました。ヘッダーを外した同じ設定では、画像ツール自体が出ませんでした。

テストは macOS 上の Codex CLI 0.165.0 で、カスタムプロバイダーには自社の API ゲートウェイである OmniaKey を使いました。

カスタムプロバイダーで imagegen が消える理由

Codex 0.165.0 は、モデルに画像ツールを渡すかどうかを 1 つの関数で決めます。見るのはプロバイダー設定と、保存済みのサインインです：image_generation_available。

requires_openai_auth = false で actor ヘッダーなし：画像ツールは出ません。この設定で走らせると、Codex は「I don’t have a built-in image generation tool available in this session.」（このセッションには内蔵の画像生成ツールがありません）と返しました。
requires_openai_auth = false に x-openai-actor-authorization を足す：ツールが出ます。ヘッダーありで回した 3 回（新規作成、編集、透明ステッカー）はいずれも呼び出せました。
requires_openai_auth = true で API キーにサインイン：画像ツールは出ません。Codex 0.165.0 のコードでは、この判定は ChatGPT のサインインを求めており、API キーのサインインは数えません。

この判定の裏には小さな条件が 2 つあります。どちらも Codex 0.165.0 のコードにあります。無料の ChatGPT プランのサインインが保存されていると、カスタムプロバイダーでもツールは隠れます。もう 1 つは、チャットモデルが画像入力を受け付けることです。Codex は自前の一覧にないモデル名については、画像を受け付ける前提で扱います。

ツールが出ないときの返答は 2 通りです。ヘッダーなしの実行のように、内蔵の画像ツールがないと Codex が答える場合。imagegen スキルが CLI の代替を案内し、そちらで OPENAI_API_KEY を求める場合です。

imagegen をオンにする config.toml

~/.codex/config.toml を開きます。中継サーバーのプロバイダーブロックに http_headers の行を足し、requires_openai_auth が false（既定値）であることを確認します。

toml

model = "gpt-6.1-sol"            # 中継サーバーが提供するチャットモデル
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          # Codex 0.165.0 では既定でオン

model と model_provider はトップレベルのキーです。最初の [section] 行より上に置きます。TOML は [section] の見出し以降の行を、すべてそのセクションの一部として読むためです。

requires_openai_auth = false は、Codex に環境変数のキーを使わせます。変数名は env_key で指定したものです。OpenAI の認証ページ（2026 年 10 月 29 日確認）には「When requires_openai_auth = true, Codex ignores env_key.」（true のとき、Codex は env_key を無視する）とあります。
http_headers に入れるのが actor ヘッダーです。OpenAI の設定リファレンスはこれを「Static HTTP headers added to provider requests」（プロバイダーへのリクエストに足す固定ヘッダー）と呼んでいます。Codex は値が空でないことだけを確認するので（Codex のソースの該当箇所）、local-relay はプレースホルダーであってパスワードではありません。
[features] image_generation = true は 0.165.0 では省略できます。機能は安定版で既定オン、codex features list は image_generation stable true と表示します。実行時はこの 2 行を書いていません。
wire_api = "responses" は、OpenAI の設定リファレンスが対応する唯一の値です。

キーを設定して Codex を起動します：

bash

export RELAY_API_KEY="your-relay-key"
codex

Codex がすでに動いているときは、いったん終了して新しいセッションを開きます。新しい設定はそこで読み込まれます。

1 枚生成して、ファイルの場所を確かめる

2026 年 10 月 29 日の実行はカスタムプロバイダー経由です。ヘッダーなしで確認した実行 2 では画像はできませんでした。ほかの 3 回は、どれも 1024×1024 の PNG を 1 枚保存しました。時間は画像呼び出しだけの値で、ターン全体の時間ではありません。

実行	依頼した内容	画像呼び出し
1	新しいアプリアイコン	29.0 s
3	実行 1 の画像を編集	37.6 s
4	透明なステッカー	19.8 s

実行 1 はプロンプト 1 つだけです：

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 はプロンプトに $imagegen がないのに、自分から imagegen スキルを開き、そのあとツールを呼びました。呼び出しは 29.0 秒で、ターンは 1024×1024 の PNG 1 枚で終わりました。

ファイルは ~/.codex/generated_images/<session id>/<call id>.png に置かれます。~/.codex は CODEX_HOME の既定値です。パスを表示したのは、プロンプトで尋ねたからです。画像をプロジェクトで使うなら、保存先をプロンプトに書きます。スキルが Codex に移動かコピーを指示します。

既存の画像を編集する

実行 1 の PNG を inkwell.png として作業フォルダーに移し、こう頼みました：

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 はファイルを referenced_image_paths に入れたので、リクエストは /images/edits に送られました。呼び出しは 37.6 秒で、元の inkwell.png はそのまま残りました。OpenAI の画像生成ページ（2026 年 10 月 29 日確認）には「When editing an existing image, say exactly what should change and what must stay the same.」（既存の画像を編集するときは、変える点と変えない点を正確に伝える）とあります。残りは GPT-Image 2 プロンプトガイドにまとめてあります。

新しい画像

1 回の編集後

どちらも 2026 年 10 月 29 日に Codex CLI 0.165.0 の内蔵画像ツールから、カスタムプロバイダー経由で生成したものです。編集で頼んだのは背景の変更だけでした。ペン先の形、大きさ、位置はそのままです。

透明な背景

実行 4 はステッカーを頼みました：

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 は transparent_background を true に設定し、呼び出しは 19.8 秒でした。保存された PNG はピクセルの 85.0% が完全な透明です。OpenAI の Images API リファレンスは、gpt-image-2 の透明背景を「in preview」（プレビュー中）としています。今回の実行では成功しましたが、プレビュー機能のままです。

2026 年 10 月 29 日の実行 4。透明な背景を持つ PNG を市松模様の上に置き、透明な部分が見えるようにしています。ピクセルの 85.0% が完全な透明です。

中継サーバーが返すもの（gpt-image-2、b64_json）

新規の画像は POST <base_url>/images/generations、編集は POST <base_url>/images/edits に送られます。どちらも JSON で、モデルは gpt-image-2、つまり中継サーバーが提供する必要がある GPT-Image 2 の ID です。品質とサイズは "auto"、background は "opaque" か "transparent" で、リクエストに response_format と n は入りません。base URL もキーもチャットのリクエストと同じです。編集では元画像をファイルアップロードではなく data URL として JSON の中に入れます。

Codex が読むのは、created と data リストを持つ JSON の返答で、b64_json はその最初の項目にあります。ほかのフィールドは無視されます（images.rs）。解析に失敗すると、メッセージは「failed to decode image generation response:」で始まります。

Codex を使わずに中継サーバーを確認できます。次を 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]))'

base URL を自分のサーバーに向け、キーを RELAY_API_KEY としてエクスポートします。2026 年 10 月 29 日に自社ゲートウェイへ実行すると、25.0 秒で HTTP 200 が返り、こう表示されました：

text

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

この一覧に b64_json がなければ、Codex も同じ返答で失敗します。サーバーがエラーを返したときは、確認スクリプトがエラーをそのまま表示します。

画像をファイルとして保存する中継サーバーはここでつまずきます。同じ Images API リファレンス（2026 年 10 月 29 日確認）は、response_format を「Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images」（廃止された画像モデル向けの旧形式パラメーター。GPT 画像モデルは非対応で、常に base64 で返す）とし、b64_json を「Returned by default for GPT image models」（GPT 画像モデルでは既定で返る）と説明しています。OpenAI の返答をそのまま渡す中継サーバーは問題ありません。リンクだけを返す中継サーバーは Codex を失敗させます。

OmniaKey のゲートウェイも、2026 年 10 月 29 日の修正まではこの問題を抱えていました。修正の記録には、Codex が「missing field b64_json」で失敗したとあります。いまは呼び出し側が URL を求めない限り、ゲートウェイは b64_json を残します。

中継サーバーがこの確認を通らない場合、OmniaKey なら gpt-image-2 と gpt-6.1-sol のようなチャットモデルを 1 つのキーで使えます。画像の返答には b64_json が入ります（上の確認のとおりです）。プロバイダーブロックに base_url = "https://api.omniakey.com/v1" を設定し、env_key が指す変数に OmniaKey のキーを入れます。ファイルの残りは Codex CLI ガイドに、現在の料金は料金ページにあります。

エラーと対処

Codex が画像ツールを持っていないと言う

最初の節の条件のどれかが満たされていません。http_headers の行を足し、requires_openai_auth = false と env_key はそのままにして、新しいセッションを始めます。それでも出ないときは codex login status を実行します。無料の ChatGPT プランなら、codex logout で保存済みのサインインを消せば、env_key のキーだけで足ります。

Codex が OPENAI_API_KEY を求める

内蔵ツールが使えないため、imagegen スキルが CLI の代替 scripts/image_gen.py を案内しています。これには OPENAI_API_KEY が必要です。代わりに上の設定で内蔵ツールを直します。内蔵モードのキーは env_key から来ます。

failed to decode image generation response: missing field b64_json

中継サーバーが b64_json なしで返しています。多くは保存したファイルへのリンクだけです。中継サーバーの節の確認スクリプトを実行し、結果を運用担当に送ります。Codex は data の最初の項目に base64 文字列を求めています。

画像リクエストが model_not_found で失敗する

そのキーには、この中継サーバー上の gpt-image-2 がありません。Codex は常にこの ID を送り、設定で変える方法はありません。自社ゲートウェイで提供していない画像モデルに投げると、HTTP 503 とコード model_not_found が返りました。gpt-image-2 を一覧に持つキーと中継サーバーを使ってください。

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

チャットのリクエストが切れ、Codex が再試行しました。カウンターは 5 回中の何回目かを示します。実行 1 で 1 回（「Concurrency limit exceeded for account, please retry later」）、実行 3 で 1 回（転送エラー）出て、どちらも再試行のあとに完走しました。繰り返すときは中継サーバーの上限を確認します。チャット側の不調は Codex 互換性キットにまとめてあります。

よくある質問

imagegen に OPENAI_API_KEY は必要ですか？

いいえ。内蔵モードのキーは env_key で指定した変数から来ます。OPENAI_API_KEY を読むのは、スキルの CLI 代替だけです。

別の画像モデル、サイズ、品質を選べますか？

Codex 0.165.0 では選べません。ツールは gpt-image-2 を品質とサイズ "auto" で送り、config.toml にこれらの設定キーはありません。実行で得た画像はすべて 1024×1024 でした。別のサイズやモデルが必要なら、中継サーバーの画像エンドポイントを直接呼びます。

$imagegen は自分で入力する必要がありますか？

いいえ。実行では Codex が自分から imagegen スキルを開きました。OpenAI のドキュメントによると、プロンプトに $imagegen を書くとスキルを明示的に呼び出します。Codex が自分で選ばないときには助けになります。

Codex デスクトップアプリでも使えますか？

デスクトップアプリは試しておらず、確認したのは CLI だけです。コミュニティの修正リポジトリによると、起動中の Codex Desktop は新しい環境変数を読みません。macOS 用スクリプトが LaunchAgent を入れ、そのあと Codex を完全に終了して新しいタスクを開く手順になります。

出典

OmniaKey の API キーを作成 GPT-Image 2 を見る