| name | ccskill-gptimage |
| description | Skill for image generation needs.
Generate and edit high-quality images via OpenAI gpt-image-2 (ChatGPT Images 2.0).
Strong at multilingual text rendering (Japanese included), complex instruction following,
reference-image fidelity, and dense-text infographics.
|
ccskill-gptimage Image Generation Skill
Overview
Generates and edits images via OpenAI gpt-image-2. The user only describes intent — Claude composes the structured prompt, parameters, and cost-optimized choices from conversation and project context. Sister skill: ccskill-nanobanana (Gemini 3 Pro Image) — see the comparison table below.
Prerequisites
- The repo's
./install.sh has been run — it deploys the ccskill-gptimage command to ~/.local/bin (PATH) and registers this skill at the user level. If the command is not found, fall back to direct invocation: $CCSKILL_GPTIMAGE_DIR/venv/bin/python $CCSKILL_GPTIMAGE_DIR/generate_image.py ... (requires the CCSKILL_GPTIMAGE_DIR env var pointing at the repo).
- At least one backend must be available:
- Codex CLI (recommended for ChatGPT subscribers):
brew install codex + codex login. No API key, no extra billing.
- OpenAI API key: set
OPENAI_API_KEY (env or .env in the repo). Your Organization must be Verified (unverified orgs get 403).
- Default
--backend auto prefers Codex, falls back to API on failure. Force a specific path with --backend codex or --backend api.
Usage
ccskill-gptimage generate "prompt"
Options
| Option | Description | Default | Values |
|---|
--size | Output size (auto or free WxH; see Resolution constraints) | 1024x1024 | auto / 1024x1024 / 1024x1536 / 1536x1024 / up to 3840x2160 (4K) |
--quality | Quality | auto | auto / low / medium / high |
--background | Background | auto | auto / opaque (for transparent use --model gpt-image-1.5) |
--output-format | Output format | png | png / jpeg / webp |
--output-compression | Compression (jpeg/webp) | none | 0-100 |
--output | Output directory | ./generated_images | any path |
--output-name | Output filename stem (extension auto) | timestamp | any string |
--reference | Reference image (repeatable) | none | image file path |
--mask | Mask image (transparent area editable; requires --reference) | none | image file path |
--input-fidelity | Not needed for gpt-image-2 (auto max). Only for gpt-image-1.5 | none | high / low |
--moderation | Moderation level | auto | auto / low |
--model | Model ID | gpt-image-2 | any model ID |
--backend | Generation backend | auto | auto (Codex preferred, API fallback) / codex (force Codex CLI) / api (force OpenAI API) |
Quick examples
ccskill-gptimage generate \
"A minimalist editorial poster with the exact title \"腹落ちDMARC\" in large serif Japanese font at the top, dark navy background" \
--size 1024x1536 --quality high
ccskill-gptimage generate \
"Replace only the background with a neon Tokyo street at night. Preserve the person's face and pose exactly as in the reference." \
--reference ./portrait.png --quality high
For use-case–specific prompt patterns and complete examples, see the Use Case Index below — each use case points to a file under prompts/ with Cookbook-sourced prompts you can reuse.
Prompt Design — 10 Principles (OpenAI Cookbook Section 2)
Source: GPT Image Generation Models Prompting Guide (retrieved 2026-04-23). Each principle below is a direct Cookbook recommendation; details and example prompts are in prompts/*.md.
- Structure + Goal — order as
background/scene → subject → key details → constraints. Include the intended use (ad, UI mock, infographic) to set mode and polish.
- Prompt Format — paragraph / JSON / tag / bullets all work. Pick what's easiest to maintain.
- Specificity + Quality Cues — be concrete about materials, shapes, textures, medium. For photorealism, put
photorealistic directly in the prompt. Specify physical scale / aspect ratio numerically (about 8–9 inches tall, A4 size, portrait 3:1, smartphone-sized) — concrete dimensions stabilize proportions far better than vague tall/small (verified in macaroni-package composite dogfooding).
- Latency vs Fidelity — start with
quality='low' while iterating. For small text, infographics, close-up portraits, compare medium/high before shipping.
- Composition — specify framing (close-up, wide, top-down), angle (eye-level, low-angle), lighting (soft diffuse, golden hour), and placement (
logo top-right, subject centered).
- People, Pose, and Action — describe scale, body framing, gaze, object interactions (e.g.
full body visible, feet included, looking down at the book, not at the camera).
- Constraints — what to change vs preserve — state exclusions explicitly (
no watermark, no extra text). For edits, say change only X + keep everything else the same, and repeat the preserve list each iteration.
- Text in Images — put literal strings in quotes or ALL CAPS + specify typography (font style, size, color, placement). For tricky words, spell letter-by-letter. Use
medium/high for small text.
- Multi-Image Inputs — reference each input by index + description (
Image 1: product photo…, Image 2: style reference…) and describe interaction (apply Image 2's style to Image 1).
- Iterate Instead of Overloading — start clean, refine with small single-change follow-ups (
make lighting warmer, remove the extra tree) instead of mega-prompts.
Use Case Index
When the user's intent matches a row below, read the linked file under prompts/ to get the Cookbook-sourced prompt pattern, parameters, and gpt-image-2-specific notes. Progressive disclosure: load only what you need.
Generation (text → image)
| Intent | Prompt guide | Recommended params |
|---|
| Infographic / diagram / pitch deck slide / chart | prompts/infographics-and-diagrams.md | 1024x1536 or 1536x1024, high |
| Photorealistic candid / historical scene | prompts/photorealism.md | 1024x1536, medium–high |
| Logo / brand mark | prompts/logo.md | 1024x1024, high |
| Ad / marketing visual / text-in-image | prompts/ads-and-marketing.md | 1024x1536, high |
| Comic strip / storyboard | prompts/comic-and-storyboard.md | 1024x1536, high |
| Mobile / Web UI mockup | prompts/ui-mockups.md | portrait for mobile, landscape for web, high |
| Character consistency / concept art / keepsake | prompts/character-and-concept.md | 1024x1536, medium–high |
| Cultural atmosphere (Japanese signage, streetscapes) | prompts/cultural-atmosphere.md | 1024x1536 or 1536x1024, high |
Editing (text + image → image)
See prompts/README.md for the full catalog and cross-references.
gpt-image-2 specific constraints (memorize these)
These apply to every use case and are critical context when composing prompts.
No transparent background
--background transparent returns 400. To produce transparent PNG, pick one of:
- Post-process with
rembg (recommended — preserves gpt-image-2's text-rendering and layout strengths):
ccskill-gptimage generate "... on plain white background"
rembg i generated_images/<image>.png generated_images/<image>_alpha.png
- Switch to
gpt-image-1.5 (supports --background transparent natively)
- Use
ccskill-nanobanana
input_fidelity is unnecessary (auto max fidelity)
gpt-image-2 always processes input images at maximum fidelity automatically. Specifying --input-fidelity returns 400. This is a feature, not a missing parameter — reference preservation is in fact strong. Just write explicit Preserve … clauses in the prompt.
Note: The Cookbook's edit-chapter examples (5.6, 5.7, 5.8, 5.9) show input_fidelity="high" in their parameter blocks. Do not carry this parameter over when using gpt-image-2 — this skill's CLI validator strips it automatically if provided, but cleaner to omit it from prompts/scripts altogether.
Trade-off: input-image tokens grow with auto-max-fidelity, so don't pass unnecessary references — it costs more.
Edit API always regenerates the full canvas
Even with a mask, gpt-image-2's edit endpoint re-renders every pixel. Cookbook quote:
"Masking with GPT Image is entirely prompt-based. The model uses the mask as guidance, but may not follow its exact shape with complete precision."
The auto-max-fidelity typically preserves non-target regions down to UI text and serial numbers — but it's not pixel-perfect. See Local editing strategy below for when this matters.
Other constraints
- Organization Verification required (unverified → 403)
- Rate limits: Tier 1 = 5 IPM (production needs Tier 3+)
- Timeout: up to 2 min for high-quality/complex prompts — set SDK timeout ≥ 120 s
- Response:
b64_json only (no URLs)
- Not supported: function calling, structured outputs
- Resolution:
--size accepts auto or any WxH, validated against gpt-image-2's constraints — each side a multiple of 16, longest side ≤ 3840px (up to 4K, e.g. 3840x2160), aspect ratio ≤ 3:1, total pixels 655,360–8,294,400. Violations are rejected with a specific error before any API call. --backend api honors the exact size; --backend codex is non-deterministic and only warns. Common presets: 1024x1024 / 1024x1536 / 1536x1024. (Verified 2026-06-11: 3840x2160 generated at exact resolution via --backend api.)
Local editing strategy
When the user wants to edit only a small region of an existing image (e.g. anonymize a map inside a UI screenshot), choose based on how strictly the surroundings must stay:
| Goal | Recommended approach |
|---|
| Replace one region; surroundings redrawn at very high fidelity but not pixel-identical (UI text usually survives) | --reference + strong Preserve absolutely everything else exactly as in the reference: … prompt that enumerates the surrounding elements (headers, dates, button labels, logos, quoted text). Often good enough for blogs / docs. |
| Re-render only one small area; other areas should be left as-is, but the model has a strong visual bias on the target area | --reference + --mask (see "Mask edit" below). Mask shape is soft guidance, not strict — but localizing the model's attention often improves the chance of overriding interpretation bias on small ambiguous objects. |
| Pixel-perfect preservation outside the edited region (legal evidence, regulated screenshots) | Hybrid: crop → edit → paste back with Pillow / ImageMagick. gpt-image-2 only edits the cropped tile; the rest is untouched bit-for-bit. |
| Composite from multiple images | --reference a.png --reference b.png … (no mask) + goal-oriented prompt. See prompts/scene-composite.md. |
Two prompt patterns for approach 1:
- Enumerate what to preserve — list every visible element by name and quoted text. The more you name, the stronger the preservation.
- Replace only X —
"Replace ONLY the map area with [fictional content]. Do not change any layout, font, color, or text outside the map rectangle."
Real-world validation: single --reference --quality high call has been observed to replace a map area inside an Apple Business "lost mode location" screenshot with fictional content while preserving surrounding UI down to device serial numbers — small UI text at output resolution remains readable.
Mask edit — focused regeneration of a small region
Pass an alpha-channel PNG with --mask. Transparent pixels (alpha = 0) are the editable region, opaque pixels are protected. Per the OpenAI Cookbook:
"Masking with GPT Image is entirely prompt-based. The model uses the mask as guidance, but may not follow its exact shape with complete precision."
This means:
- The mask does not strictly protect pixels outside the transparent region — but in practice, opaque areas are kept very close to the input
- The mask does help focus the model's attention to the editable region, often overriding visual interpretation bias on the target area
- Effects are not guaranteed — masks may improve a stubborn small-region issue, or may not
Workflow recommendation
Mask creation is outside this skill's scope — produce the mask using your favorite image editor (Pixelmator / Photoshop / GIMP / Preview is generally too limited). Iterate with cheap quality first:
- Mask creation — open the base image in an image editor, fill the editable area with full transparency (alpha = 0), keep the rest fully opaque, export as PNG with the same dimensions as the base
- Try cheaply — run
--mask <mask.png> --reference <base.png> --quality low (or medium) a few times with different prompts. Cost ¥1–¥12 per try
- Promote winners to high — when an iteration looks promising, re-run with
--quality high for the final asset, or pass the chosen iteration as a new --reference for further refinement
Real-world validation
Replacing a small ambiguous foreground object (a Japanese ceramic chopstick rest that gpt-image-2 kept misinterpreting as fork prongs in 4 successive --reference-only edits) was visibly improved by adding --mask over that region. Result was not perfect but moved clearly toward the intended ceramic shape — confirming masks are useful for breaking through stubborn interpretation bias on small regions, even if not pixel-precise.
Backend selection (--backend)
Two transports reach the same gpt-image-2 model. Pick automatically (auto) or pin one.
| Backend | When to use | Cost | Caveats |
|---|
codex | ChatGPT subscriber with Codex CLI installed | Subscription quota (no extra billing) | Pixel-exact --size not guaranteed (agent-mediated); --mask not supported |
api | Has OPENAI_API_KEY + Verified Organization | Pay-as-you-go ($0.006–$0.211/image) | All parameters honored exactly |
auto (default) | Either or both | Codex first, then API | Falls back to API if Codex fails and OPENAI_API_KEY is present |
When the user has both available, prefer auto — Codex saves money, API catches anything Codex can't do.
Force --backend api when:
--mask is needed (Codex can't pass masks)- Pixel-exact
--size is required (Codex's image_gen tool may return slightly different dimensions)
- Strict reproducibility is needed (Codex's agentic layer adds non-determinism)
Cost optimization advice (below) applies to both backends — the pricing difference is who pays (you per-image vs. ChatGPT subscription quota), not the model behavior.
Cost optimization
Iterate with --quality low ($0.006/image). Ship with medium ($0.053) or high ($0.211).
Counter-intuitive: portrait 1024×1536 at high is $0.165 — cheaper than square 1024×1024 at high ($0.211). Prefer portrait whenever the use case allows.
| Quality | 1024×1024 | 1024×1536 | 1536×1024 |
|---|
| low | $0.006 | $0.011 | $0.011 |
| medium | $0.053 | $0.080 | $0.079 |
| high | $0.211 | $0.165 | $0.210 |
Sister skill comparison
| Use case | First choice | Reason |
|---|
| Posters with Japanese/kanji text | ccskill-gptimage | Strongest text rendering |
| Business infographics / pitch slides | ccskill-gptimage | Strong instruction following + text layout |
| Editing / partial modification | ccskill-gptimage | Auto max input fidelity |
| Photo / illustration single visuals | Either | Comparable cost |
| Transparent PNG (logos, icons, sprites) | Either | gpt-image-2 can't natively, but (a) --model gpt-image-1.5, (b) rembg post-processing, (c) ccskill-nanobanana all work |
| 4K output | Either | gpt-image-2 supports up to 4K (3840x2160, longest side ≤ 3840px) via --backend api; nanobanana also works |
Output
Each image is saved alongside a metadata JSON sidecar ({name}.{ext}.json) containing the prompt, revised_prompt, parameters, and timestamp — useful for reproduction and refinement.
revised_prompt: gpt-image-2 may return a paraphrased prompt. This skill prints it as [Revised] ... and saves it to the sidecar. Use it as a signal to refine follow-up prompts.
Browsing generated images
Every image is also copied into a shared gallery store (~/.ccskill-gptimage/gallery, override with CCSKILL_GPTIMAGE_GALLERY_DIR) alongside ccskill-nanobanana and ccskill-omniflash output. Install ccskill-gallery and run:
ccskill-gptimage browse
This delegates to ccskill-gallery browse (--port/--bind/--no-open pass through). Without ccskill-gallery installed, it just prints where the images are stored.
Troubleshooting
- Not sure what's wrong? → run
ccskill-gptimage doctor for a quick environment + backend diagnosis (it never reads secret files; reports are presence-based)
- Claude Code keeps asking permission to run
ccskill-gptimage → add Bash(ccskill-gptimage:*) to permissions.allow in ~/.claude/settings.json (the installer intentionally does not modify your settings)
- 403 Forbidden → check Org Verification
- Rate limit → upgrade tier or use
--quality low while iterating
- Timeout → check network; set SDK timeout ≥ 120 s
- Japanese text broken → wrap in quotes; specify font (
serif Japanese font); use quality=high
- 400 on
--input-fidelity → omit it (gpt-image-2 auto max fidelity); only valid for --model gpt-image-1.5
- 400 on
--background transparent → see transparent section
- "Image not found" with Codex backend → newer Codex CLI (v0.141.0+) returns the image in the session log instead of writing a file, so older versions of this skill fail to recover it. Run
git pull in the repo to update.
