qwwiwi/codex-gpt-image-2-subscription/codex-image

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

Rule – a paid OpenAI API key is for image models only

The default path is the subscription (below) and needs no key. If the owner also gave you an OpenAI API key for the paid image path (env OPENAI_API_KEY or a key file the owner configured), use it for IMAGE models ONLY (gpt-image-2.x, chatgpt-image-): deep-detail 2K–4K renders the subscription cannot do. NEVER use it for text/LLM models (gpt-, o*, embeddings, audio, Responses with a text model, agents, Codex runs), never put it in another service's env, never pass it to other agents, never print it.

Before generating: brief first

Image models work best with references plus a structured brief (ТЗ). Mandatory flow for ANY agent:

1. python3 scripts/brief.py questions --type <youtube-cover|banner|post-illustration|infographic|sticker|logo|other> – ask the requester every question (the questionnaire is in Russian).
2. Collect refs: a registry preset (brief.py presets, your own references/brands.json – see references/README.md) and/or files from the requester, each with a role (subject|face|style|logo|background|layout|clothing).
3. brief.py init brief.json --type <t> → fill in the answers.
4. brief.py check brief.json must pass (exit 0). On failure it lists what to ask – go back to the requester.
5. brief.py prompt brief.json → prints the English prompt + the exact run.sh command (or API params).
6. Generate, then check the result per «After every run» below.

Exception: the requester says «без вопросов» or gives a complete brief – skip the questions, still run check. Faces: only approved frames (eyes fully open, direct gaze). Keep rejected frames (blink, squint, side gaze) in a folder named _rejected/ – check refuses any ref from it. brief.py is offline: no network, never reads any API key. Example: examples/youtube-cover.brief.json (uses the youtube-dark preset from references/brands.example.json).

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; the latest frontier GPT model (default gpt-6.1-sol, override with env CODEX_IMAGE_HOST_MODEL) invokes it, gpt-image-2 renders.

Setup: works with the official Codex plugin for Claude Code

This skill is meant to run together with the official OpenAI Codex plugin for Claude Code – https://github.com/openai/codex-plugin-cc. The plugin connects Claude Code to Codex (tasks, review) and sets up the Codex CLI login that this skill uses.

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/codex:setup        # checks Codex CLI and the ChatGPT login (or run: codex login)

The plugin itself does not draw images: this skill's script takes the same login (~/.codex/auth.json) and calls the Codex backend directly for image generation.

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]

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:<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.
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

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).

Routing: subscription vs official API

Subscription path (Codex/ChatGPT OAuth) is fixed: model gpt-image-2, size=auto, quality=auto, <=5 reference images, transparent_background only (~1.5 MP, e.g. 1536x1024). No model choice, no 2K/4K, no complexity, no markup/mask, no SVG, no n>1.

Use subscription (default) for drafts, post illustrations, iterations, transparent PNGs. Switch to the official API (/v1/images/generations|edits, requires the owner's OK, it costs money) when:

• output must be > 1536 px on the long edge (2K banners, 4K covers, print);
• dense small text / infographics / complex layout;
• precise local edit (markup overlay or mask), or more than 5 references (API allows 16);
• SVG logo or animated GIF (2.6 only, output_format: svg|gif, n=1, generations only);
• bulk runs (Batch, -50%, gpt-image-2 / 2.5 only; 2.6 has no Batch, no Responses tool).

API model choice: gpt-image-2.6-flare default; gpt-image-2.6-sunburst for detail and edits; gpt-image-2.5-* when Batch or Responses multi-turn is needed (3-4x cheaper at low/medium).

API size rules: WxH multiples of 16, ratio <= 3:1, edge <= 3840, 655,360-8,294,400 px. Presets: 1k=1024x1024, 2k=2048x2048, 2k-wide=2048x1152, qhd=2560x1440, 4k=3840x2160, 4k-tall=2160x3840. Above 2560x1440 is experimental: inspect the result. Params: quality low|medium|high|xhigh|max (detail), complexity low|medium|high (2.6, planning, default high, free). Tune one at a time. Omit input_fidelity.

Output-token cost ($30/M), quality high / max: 1024^2 $0.053 / $0.21; 2048^2 $0.11 / $0.43; 3840x2160 $0.10 / $0.40. 2.6 low/medium cost 4.2x/3.3x of 2.5. Print the estimate before an API call.

Prompt template (official 2.6 guide): Intent/use -> Scene -> Subject -> Details (materials, light, color, medium) -> Text (quoted, position, typography, "render exactly once", "no extra text") -> Constraints ("change only X", list what to preserve). Number references and give each a role (subject/style/clothing/background). No filler ("8K", "masterpiece"). Draft at low/medium and small size, then finalize at high.

After every run: open the image and check text, identity, edits-only-where-asked, alpha channel if transparency was requested; log model/size/quality actually used. Upscaling a subscription image to 2K/4K is a fallback only; prefer native API size.

Key for the API path: see the rule at the top (image models only). Tested 2026-11-05: 2.6 flare/sunburst, 2.5 flare, gpt-image-2 all accept 3840x2160 high (~$0.10 for 2.5/2.6); 2.6 GIF works at 512x512 (9 frames), 1024 rejected; sunburst rendered infographic digits correctly where flare slipped one digit per image – use sunburst for numbers.