codex-imagegen

Imported from zlsbksdxl/codex-imagegen (plugins/codex-imagegen/skills/codex-imagegen/SKILL.md). Install upstream with npx skills add zlsbksdxl/codex-imagegen --skill codex-imagegen. Copyright stays with the author.

Codex ImageGen

Overview

Use the host Codex ImageGen capability first. The Skill is an instruction layer; the host tool performs the actual model call and uses gpt-image-2. This plugin cannot manufacture a missing host tool, so when the host capability is unavailable it offers a separate paid API path through the bundled script. Keep generated assets in the project or the user-requested output directory and never claim that a generated concept is an installed real-world state.

Workflow

1. Classify the request as generate (new image) or edit (change an existing image).

2. Collect the prompt, output path, aspect ratio or size, quality, exact text, references, and constraints.

3. Prefer the built-in route:

   • Invoke the host image-generation capability explicitly with $imagegen when the user or the current task can access it.
   • For a local reference image, attach it to the task or load it into the conversation before asking for an edit.
   • Use one generation call per distinct requested asset. Do not use one prompt with unrelated views as a substitute for separate assets.

4. If the host capability is not available, report that fact. Use the API route only when the user has approved API usage and billing. By default, the script reads the active provider's key and base_url from Codex's local config. Use explicit API settings only when the user asks for an alternate endpoint. Run:

   python3 <plugin-root>/scripts/generate_image.py --prompt "..." --output <path>

   The default is the active Codex provider. Use --api-base-url https://api.openai.com/v1 for the official endpoint, or --no-codex-config plus OPENAI_API_KEY for a fully separate environment. For edits, add one or more --image <reference> arguments and optionally --mask <mask.png>.

5. Inspect the output and validate the subject, composition, text, file format, and invariants. If text accuracy matters, prefer a clean image plus a deterministic local annotation pass.

6. Report the exact saved path, which route was used, and any unresolved limitation.

Prompting

Use concrete visual language. State the intended use, subject, setting, composition, style, lighting, dimensions, and constraints. For edits, explicitly say what must remain unchanged.

Example:

$imagegen
Edit the attached warehouse photo. Preserve the room geometry, windows, floor, lighting, and camera perspective. Add a clearly hypothetical two-bay product-rack layout on the north side and keep the south shooting zone open. Mark it as a planning visualization; do not present it as already installed.

API Route

The script uses the OpenAI Image API with gpt-image-2. The official API supports generation at /v1/images/generations and edits at /v1/images/edits. GPT Image 2 automatically processes image inputs at high fidelity; do not pass input_fidelity. Transparent backgrounds are not supported by this model, so do not promise native alpha output.

Required environment:

export OPENAI_API_KEY='...'

Default Codex config lookup:

python3 scripts/generate_image.py \
  --prompt "A clean architectural planning visualization" \
  --output outputs/studio-plan.png

This reads model_provider, then model_providers.<active>.OPENAI_API_KEY and base_url from ~/.codex/config.toml. It does not use experimental_bearer_token, which is a Codex session credential rather than an Image API key.

Generation:

python3 scripts/generate_image.py \
  --prompt "A clean architectural planning visualization of a photo studio" \
  --size 1536x1024 \
  --quality medium \
  --output outputs/studio-plan.png

Edit:

python3 scripts/generate_image.py \
  --mode edit \
  --image reference.jpg \
  --prompt "Change only the storage wall; preserve the room geometry and camera perspective" \
  --output outputs/edited.png

Read references/api.md only when troubleshooting authentication, edit inputs, sizes, or output formats.

Guardrails

• Never print or persist OPENAI_API_KEY.
• Use the active Codex provider by default; explain that its key and endpoint are being reused.
• Use --no-codex-config when the user explicitly asks for an independent API configuration.
• Ask before switching from the included host route to the paid API route.
• Do not overwrite an existing image unless the user explicitly requests replacement.
• Keep user-provided reference images unchanged; save edited results as a new file by default.
• Distinguish AI-generated visualizations from real installation, measurement, or construction documentation.