imagegen

Image Generation Skill

Adapted from OpenAI Codex's imagegen skill for Pi. Original source: https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples/imagegen Subscription guidance reconciled with Codex rust-v0.168.0-alpha.3, including the model-facing image-tool instructions. Required Pi modifications: use Pi's codex_generate_image tool name, Pi artifact paths, and the bundled helper path.

Generates or edits images for the current project (for example website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, or infographics).

Top-level modes and rules

This skill has exactly two top-level modes:

• Default Pi tool mode (preferred): Pi codex_generate_image tool for new image generation, edits using up to five local or recent conversation images, reference variants, and native transparent-image requests. Does not require OPENAI_API_KEY.
• Fallback CLI mode: scripts/image_gen.py CLI. Use only when the user explicitly asks for or confirms the CLI/API/model path. Requires OPENAI_API_KEY and separate API billing.

Within CLI fallback, the CLI exposes three subcommands:

• generate
• edit
• generate-batch

Rules:

• Recover existing current-branch artifacts with tools.codex_list_image_artifacts({}) after a later script failure; inspect availability and use returned paths instead of generating again. Listing consumes no image quota. Continue paginated listings with revision/nextOffset.
• Direct and artifact requests share bounded account admission (two active, eight queued). Queue time counts toward the five-minute total deadline. Queueing does not authorize extra assets; cancellation after dispatch can still consume quota. Reported metadata is not measured pixel properties or verified cost.
• Use the Pi codex_generate_image tool by default for new image generation requests.
• codex_generate_image is model-only; call it directly, never through codemode. For scripted workflows use tools.codex_generate_image_artifact(...), which returns { summary, artifact: { path, mimeType, byteCount }, savedPath?, saveWarning? } without image bytes. Both tools support the same generation/edit parameters and subscription login. Use Pi 1.4.0 or later.
• To display an artifact, call tools.read({path: result.artifact.path}), then image(block) if the returned value is an image block. Pi can resize or omit an un-decodable display image; the original remains unchanged. Never print or store base64 image bytes. Pass artifact paths directly through referencedImagePaths for chained edits.
• Artifact save: "none" still writes a private temporary original; it means no persistent user copy. Completed originals survive script failure/timeout, reload, shutdown, and branch changes until user/OS cleanup. Copy needed project assets to persistent storage. Run /image-artifacts to recover current-branch paths without generation. Recent-image selection includes branch-local original artifacts, even if never displayed; reference-size limits still apply.
• Do not retry artifact-storage failures automatically. Known storage failures reject before generation; failures after backend success can already have consumed quota. A successful requested persistent save can be used as recovery if the temporary write fails. If neither succeeds, the tool explicitly reports that no artifact is recoverable.
• Image login is separate from chat: use /login codex-images and complete the ChatGPT OAuth flow in Pi. The Codex app is not required. Existing legacy Pi openai-codex OAuth can be a fallback; new openai plan-sharing chat OAuth cannot generate images. Never ask the user to paste login URLs or tokens into chat.
• Legacy OAuth is used only when owned image credentials are absent. Configured but unusable codex-images credentials block fallback; repair that login instead of switching accounts.
• codex-images has no native Pi image-model entry. Do not substitute models.generateImages() or an OpenRouter image model for these subscription tools: native image calls do not inherit their approval, save/recovery, output-size, or billing contracts.
• The tool's model parameter selects a Codex routing model, not Flare or Sunburst. Do not claim a specific served image model unless the response reports it. Read details.reportedImage for backend-reported output settings, then inspect the actual image; prompt requests for quality, dimensions, or transparency are not guarantees.
• The default routing model is gpt-6-astra. Explicit tool parameters and configuration values override this default.
• Keep the default responses transport unless the user explicitly selects images or trusted configuration selects it. images is PNG-only, uses automatic size/quality, and rejects a per-call routing model. Never switch transports automatically after a failure.
• requestedImage is intent, reportedImage is the server report, and measuredImage contains independently decoded dimensions and alpha properties. imageWarning does not authorize regeneration. Preserve originals if inspection is unavailable or a format differs.
• Do not request GIF, SVG, complexity, masks, markup, or Flare/Sunburst selection through these subscription tools. GIF client support exists upstream but server access is not verified for this extension.
• Do not automatically repeat quota, connection, timeout, or incomplete-stream failures. The remote generation may already have consumed quota.
• Use referencedImagePaths for edits when every target has a local path. Inspect unseen local targets with Pi read first. Use numLastImagesToInclude only when a target is available solely in recent conversation history. Never provide both selectors. Masks and advanced CLI-only controls still require confirmed CLI fallback.
• Do not switch to CLI fallback for ordinary generation quality, size, or output file-path control.
• For cutouts or background removal, set background: "transparent" and use PNG or WebP. For edits, preserve existing transparency unless the user asks to change it.
• Never silently switch from Pi codex_generate_image or CLI gpt-image-2 to CLI gpt-image-1.5. Treat this as a model/path downgrade and ask the user before doing it, unless the user has already explicitly requested gpt-image-1.5, scripts/image_gen.py, or CLI fallback.
• The word batch by itself does not mean CLI fallback. If the user asks for many assets or says to batch-generate assets without explicitly asking for CLI/API/model controls, stay on the Pi tool path and issue one Pi tool call per requested asset or variant.
• If the Pi tool fails or is unavailable, tell the user the CLI fallback exists and that it requires OPENAI_API_KEY. Proceed only if the user explicitly asks for that fallback.
• If the user explicitly asks for CLI mode, use the bundled scripts/image_gen.py workflow. Do not create one-off SDK runners.
• Never modify scripts/image_gen.py. If something is missing, ask the user before doing anything else.