Codex Image

codex-image — gpt-image-2 via Codex OAuth subscription

Overview

Images are generated by gpt-image-2 through the Codex/ChatGPT OAuth subscription (token from ~/.codex/auth.json, created by codex login). No API key, no per-image cost — quota is shared with the Codex subscription.

Common misconception (documented agent failure): "Codex is text-only, image generation needs OPENAIAPIKEY / DALL-E." Wrong. The Codex backend (chatgpt.com/backend-api/codex) serves the image_generation tool over the Responses API; host model gpt-5.5 invokes it, gpt-image-2 renders.

Note: the Codex Claude Code plugin (openai/codex-plugin-cc) does NOT generate images — its role is review/architecture. This skill's script bypasses the plugin and talks to the Codex backend directly using the same login.

Quick reference

# self-contained launcher — uses the skill's own venv, bootstraps it if missing
~/.claude/skills/codex-image/scripts/run.sh \
  "prompt in English" [quality] [aspect] [ref1.png ... ref5.png]

| Param | Values | Notes | |---|---|---| | quality | low (~45s) / medium (default, ~1-2min) / high (~2-3min) | | | aspect | landscape 1536x1024 / square 1024x1024 / portrait 1024x1536 | | | refN | up to 5 local image paths (png/jpg/webp) | passed as input_image data-URL content blocks; style/character/logo transfer | | output | prints path to PNG | saved in ~/.codex/cache/images/img_.png |

Prompt in English works best. Generation is slow — for high use a background call.

Hard constraints (violating any → HTTP 400 or wrong path)

1. References: max 5 images, as content blocks. {"type":"input_image","image_url":"data:;base64,...","detail":"auto"} placed NEXT TO input_text in the same user message. There is no seed parameter — for strict reproducibility a paid image API is still the better tool; for character/style/logo transfer this works.
2. Never client.images.generate() / Images API — that is the API-key path, the OAuth subscription rejects it. Only Responses API + tool image_generation (+ tool_choice={"type":"image_generation"} so the host model draws immediately).
3. stream=True and store=False are mandatory — otherwise HTTP 400 from the Codex backend.
4. input must be a LIST of message objects, not a bare string.
5. Auth: tokens.access_token (+ tokens.account_id → chatgpt-account-id header) from ~/.codex/auth.json. Required headers: OpenAI-Beta: responses=experimental, originator: codex_cli_rs.

Troubleshooting

| Symptom | Fix | |---|---| | ModuleNotFoundError: openai | run via scripts/run.sh (skill's own venv), NOT system python3 — it lacks the SDK | | Codex auth не найден | codex login (server: codex login --device-auth) | | HTTP 400 | check stream=True, store=False, input as message list | | 401/403 | token expired — re-run codex login; check account_id header | | No image in stream | model refused (policy) — rephrase prompt | | ref rejected | png/jpg/webp only, ≤15MB per file, ≤40MB total, max 5 files |

When NOT to use

• Deterministic graphics (exact typography, brand colors, diagrams): hand-author SVG → render PNG.
• Strict reproducibility / seed-based pipelines: needs a paid image API with seed support.

The skill is fully self-contained (script + own .venv, auto-bootstrapped by run.sh). Reference technique from ningzimu/codex-gpt-image (audited).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qwwiwi
• Source: qwwiwi/codex-gpt-image-2-subscription
• License: MIT

Install and usage instructions live in the source repository linked above.