| name | codex-image |
| description | Use when asked to generate an image, picture, photo, cover, banner art or illustration (сгенерируй картинку, фоточку, обложку, изображение) using the Codex/ChatGPT subscription — no OPENAI_API_KEY, no per-image billing; supports up to 5 reference images (по референсу, в стиле картинки). Also use when tempted to answer that image generation is impossible without an API key, that Codex is text-only, or that references don't work over the subscription. |
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 OPENAI_API_KEY / 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
~/.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_<ts>.png |
Prompt in English works best. Generation is slow — for high use a background call.
Hard constraints (violating any → HTTP 400 or wrong path)
- References: max 5 images, as content blocks.
{"type":"input_image","image_url":"data:<mime>;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.
- 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).
stream=True and store=False are mandatory — otherwise HTTP 400 from the Codex backend.input must be a LIST of message objects, not a bare string.- 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).
