AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--imagegen at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/cli.md

CLI reference (scripts/image_gen.py)

This file is for the fallback CLI mode only. Read it only after the user explicitly asks to use scripts/image_gen.py instead of the built-in image_gen tool.

generate-batch is a CLI subcommand in this fallback path. It is not a top-level mode of the skill.

What this CLI does

  • generate: generate a new image from a prompt
  • edit: edit one or more existing images
  • generate-batch: run many generation jobs from a JSONL file

Real API calls require network access + OPENAI_API_KEY. --dry-run does not.

Quick start (works from any repo)

Set a stable path to the skill CLI (default CODEX_HOME is ~/.codex):

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

Install dependencies into that environment with its package manager. In uv-managed environments, uv pip install ... remains the preferred path.

Quick start

Dry-run (no API call; no network required; does not require the openai package):

python "$IMAGE_GEN" generate \
  --prompt "Test" \
  --out output/imagegen/test.png \
  --dry-run

Notes:

  • One-off dry-runs print the API payload and the computed output path(s).
  • Repo-local finals should live under output/imagegen/.

Generate (requires OPENAI_API_KEY + network):

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --out output/imagegen/alpine-cabin.png

Edit:

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --out output/imagegen/sunset-edit.png

Guardrails

  • Use the bundled CLI directly (python "$IMAGE_GEN" ...) after activating the correct environment.
  • Do not create one-off runners (for example gen_images.py) unless the user explicitly asks for a custom wrapper.
  • Never modify scripts/image_gen.py. If something is missing, ask the user before doing anything else.

Defaults

  • Model: gpt-image-1.5
  • Supported model family for this CLI: GPT Image models (gpt-image-*)
  • Size: 1024x1024
  • Quality: auto
  • Output format: png
  • Default one-off output path: output/imagegen/output.png
  • Background: unspecified unless --background is set

Quality, input fidelity, and masks (CLI fallback only)

These are explicit CLI controls. They are not built-in image_gen tool arguments.

  • --quality works for generate, edit, and generate-batch: low|medium|high|auto
  • --input-fidelity is edit-only and validated as low|high
  • --mask is edit-only

Example:

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Change only the background" \
  --quality high \
  --input-fidelity high \
  --out output/imagegen/background-edit.png

Mask notes:

  • For multi-image edits, pass repeated --image flags. Their order is meaningful, so describe each image by index and role in the prompt.
  • The CLI accepts a single --mask.
  • Use a PNG mask when possible; the script treats mask handling as best-effort and does not perform full preflight validation beyond file checks/warnings.
  • In the edit prompt, repeat invariants (change only the background; keep the subject unchanged) to reduce drift.

Output handling

  • Use tmp/imagegen/ for temporary JSONL inputs or scratch files.
  • Use output/imagegen/ for final outputs.
  • Reruns fail if a target file already exists unless you pass --force.
  • --out-dir changes one-off naming to image_1.<ext>, image_2.<ext>, and so on.
  • Downscaled copies use the default suffix -web unless you override it.

Common recipes

Generate with augmentation fields:

python "$IMAGE_GEN" generate \
  --prompt "A minimal hero image of a ceramic coffee mug" \
  --use-case "product-mockup" \
  --style "clean product photography" \
  --composition "wide product shot with usable negative space for page copy" \
  --constraints "no logos, no text" \
  --out output/imagegen/mug-hero.png

Generate + also write a downscaled copy for fast web loading:

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --downscale-max-dim 1024 \
  --out output/imagegen/alpine-cabin.png

Generate multiple prompts concurrently (async batch):

mkdir -p tmp/imagegen output/imagegen/batch
cat > tmp/imagegen/prompts.jsonl << 'EOF'
{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","composition":"wide-angle, low-angle","lighting":"volumetric light rays through drifting fog","constraints":"no logos or trademarks; no watermark","size":"1536x1024"}
{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","composition":"eye-level","constraints":"no logos or trademarks; no watermark","size":"1024x1024"}
EOF

python "$IMAGE_GEN" generate-batch \
  --input tmp/imagegen/prompts.jsonl \
  --out-dir output/imagegen/batch \
  --concurrency 5

rm -f tmp/imagegen/prompts.jsonl

Notes:

  • generate-batch requires --out-dir.
  • generate-batch requires --out-dir.
  • Use --concurrency to control parallelism (default 5).
  • Per-job overrides are supported in JSONL (for example size, quality, background, output_format, output_compression, moderation, n, model, out, and prompt-augmentation fields).
  • --n generates multiple variants for a single prompt; generate-batch is for many different prompts.
  • In batch mode, per-job out is treated as a filename under --out-dir.

CLI notes

  • Supported sizes: 1024x1024, 1536x1024, 1024x1536, or auto.
  • Transparent backgrounds require output_format to be png or webp.
  • --prompt-file, --output-compression, --moderation, --max-attempts, --fail-fast, --force, and --no-augment are supported.
  • This CLI is intended for GPT Image models. Do not assume older non-GPT image-model behavior applies here.

See also

  • API parameter quick reference for fallback CLI mode: references/image-api.md
  • Prompt examples shared across both top-level modes: references/sample-prompts.md
  • Network/sandbox notes for fallback CLI mode: references/codex-network.md