Image Gen

Image Generation & Sourcing

Produce image files on disk through one of three acquisition paths. This skill is the single home for image acquisition — other skills delegate to it rather than embedding their own copy.

All <skill-dir>/... paths below are relative to this skill's own directory (its absolute path is in the location header injected when the skill loads), not the user's working directory. There is no persistent CWD across terminal calls — pass absolute paths for --output and inputs.

Preflight

1. Run scripts with uv run — every script carries PEP 723 inline dependency metadata, so uv run <skill-dir>/scripts/<name>.py … auto-installs exactly what that script needs into an ephemeral, cached environment. No pip install, no venv, nothing left behind. uv ships with the octo installer; if it's somehow missing, the fallback is pip install -r <skill-dir>/requirements.txt once, then run the scripts with python3.
2. Configure a backend for AI generation. Set IMAGE_BACKEND and the provider's own key (e.g. OPENAI_API_KEY) in the process environment, or in a .env file — see <skill-dir>/.env.example for every provider's variables and the .env lookup order. uv run <skill-dir>/scripts/image_gen.py --list-backends prints what's available. Web search (image_search.py) needs no key for CC0/public-domain providers; Pexels/Pixabay use their own keys if you want those sources.

First AI-generation run — backend setup gate (do NOT skip)

Before the first AI generation of a session (a positional image_gen.py call or image_gen.py --manifest), check whether an AI backend is configured, and if not, guide the user proactively instead of running the script and dumping its error:

1. Detect config. Is IMAGE_BACKEND set in the environment, or present in a .env on the lookup path (./.env, <skill-dir>/.env, <repo>/.env, ~/.ppt-master/.env)? If yes — and its provider key is present — proceed silently, ask nothing.
2. If no backend is configured, stop and ask the user (in the TUI/web use a question prompt; in an IM channel ask in plain language) to pick one of:
   • Configure an AI backend now — recommend a CORE backend (openai / gemini / qwen / volcengine / zhipu). Tell them exactly which env vars that backend needs (from --list-backends / .env.example), take the key, and write it for them to ./.env (project-local) or ~/.ppt-master/.env (user-level) — e.g. IMAGE_BACKEND=openai + OPENAI_API_KEY=…. Never echo the key back in chat, and never commit .env.
   • Skip AI, use keyless web search instead — run image_search.py (Openverse / Wikimedia are CC0 / public-domain, no key needed). Good when the user just wants real photos or has no API key.
   • Use the host's native image tool (Path B) — if the host (Claude Code / Codex / etc.) has its own image-generation tool, generate directly from the prompts in image_prompts.json and save to images/<filename>, skipping this script entirely. See references/image-generator.md §7 Path B.
3. When invoked by another skill that already confirmed the image source: honor it — if the caller confirmed web or host-native, do not prompt for an AI backend; only run this gate when AI generation is actually about to run with nothing configured.

Once a backend is configured this gate never fires again for the session.

Two ways to drive it

One-off — a single image right now

# AI generation
uv run <skill-dir>/scripts/image_gen.py "a serene alpine lake at dawn, soft mist, painterly" \
  --aspect_ratio 16:9 --image_size 2K --output /abs/out/dir --filename hero

# Web search (openly-licensed, downloads one best match + records the source)
uv run <skill-dir>/scripts/image_search.py "diverse engineering team in a modern office" \
  --orientation landscape --output /abs/out/team.jpg

# AI generation anchored on reference image(s) — keep a character / product / style consistent
uv run <skill-dir>/scripts/image_gen.py "the man in the reference image, now seated at a desk by a window, same face and outfit" \
  --ref /abs/refs/character.png --aspect_ratio 1:1 --output /abs/out/dir --filename avatar

--ref is repeatable (refer to them in the prompt as "image 1", "image 2" …) and accepts local paths or http(s) URLs. It is supported by the openai (routes to /images/edits), gemini and qwen backends; any other backend fails fast with a clear message rather than silently ignoring the image.

The positional-prompt form skips the manifest and leaves no audit trail — reserve it for quick fixups and standalone requests. After it finishes, present the file to the user — see Show the result.

Batch — an image_prompts.json manifest (audit trail)

The manifest is the shared contract when a caller has many images and wants a written-back status per item. Write it, then run generation; the CLI runs every Pending/Failed item and writes Generated / Failed / Needs-Manual back into the same file as each completes.

{
  "project": "my-deck",
  "deck_rendering": "vector-illustration",   // one rendering shared by all items
  "deck_palette": "cool-corporate",          // one palette shared by all items
  "color_scheme": { "primary": "#1E3A5F", "secondary": "#F8F9FA", "accent": "#D4AF37" },
  "items": [
    { "filename": "cover.png", "prompt": "...", "aspect_ratio": "16:9",
      "image_size": "2K", "page_role": "hero_page", "text_policy": "none",
      "status": "Pending" },
    { "filename": "mascot_p07.png", "prompt": "the mascot from image 1, waving ...",
      "aspect_ratio": "1:1", "reference_images": ["refs/mascot.png"],   // paths relative to this file, or URLs
      "status": "Pending" }
  ]
}

# Render the read-only Markdown sidecar for review (no network):
uv run <skill-dir>/scripts/image_gen.py --render-md /abs/images/image_prompts.json
# Generate every Pending/Failed item in parallel, writing status back:
uv run <skill-dir>/scripts/image_gen.py --manifest /abs/images/image_prompts.json

Full field reference (page_role, text_policy, type, reference_images, slice_grid/slice_names, back-compat) is in references/image-generator.md §6.

Slice a generated sheet into elements

When several small spot illustrations should share one coherent style, generate one grid sheet (a single AI item), then cut it:

uv run <skill-dir>/scripts/slice_images.py /abs/images/spot_sheet.png \
  --grid 2x3 --names icon_a icon_b icon_c icon_d icon_e icon_f --trim --alpha

--trim tight-crops each cell to its content; --alpha knocks out the flat background to transparency. Geometry rules: references/image-generator.md §4.3.