git:20260909.49cd466 to git:20260910.63e99b4

44 added, 62 removed. Audit A to A.

---

name: gpt-image-gen

- description: MUST read before generating images. Detailed prompt-crafting guide for gpt-image models, covering tool routing (native image_generation server tool vs the generate_image tool), prompt structure from subject to background, verbatim text rendering, anti-patterns, and the revised_prompt feedback loop for iteration.

+ description: MUST read before generating images. Prompt-crafting guide for gpt-image-2.5 covering tool routing (native image_generation server tool vs the generate_image tool), model and quality selection, prompt structure, exact text rendering, reference-image editing, transparent assets, output formats, and multi-turn refinement.

---

# GPT Image Generation

- How to write image prompts that come back right the first time, and how to fix them fast when they don't. Read this before your first generation call.

+ How to get the image right the first time, and how to fix it fast when it is not. Read this before your first generation call.

## Which tool

When image generation tooling is present in your tool set, pick the surface that actually exists right now:

- If a native `image_generation` server tool is available, use it. The provider runs generation server-side and returns the image in the response stream.

- - Otherwise, call the `generate_image` tool. It sends your prompt and optional reference images to the configured OpenAI-compatible endpoint and saves the result as PNG files. Its default model is `gpt-image-2.5-sunburst`; choose `gpt-image-2.5-flare` for speed or `gpt-image-2` for the previous generation. These model and parameter controls apply to `generate_image`, not the native server tool.

- Check your current tool set before choosing. Skill visibility refreshes on reload, but tool state can change mid-session (model switch, credential change), so trust the tools you can see over what this page said at startup. If both surfaces ever appear, prefer the native server tool.

- ## Prompt crafting

- This section is the core of the skill. gpt-image models reward detail, and the single most common failure mode is a one-line prompt.

- Build each prompt from six parts, in this order:

+ - Otherwise, call the `generate_image` tool. It sends your prompt and optional reference images to the configured OpenAI-compatible endpoint and saves the result as a png, jpeg, or webp file. The model, quality, size, background, and format controls below apply to `generate_image`, not to the native server tool.

- 1. Subject. Who or what, with concrete physical detail. "A middle-aged baker with flour on her forearms and a gray-streaked braid" beats "a baker".

- 2. Medium and style. One style, stated plainly: "35mm film photograph", "watercolor illustration", "flat vector poster". Pick one lane.

- 3. Composition and camera. Framing, angle, focal length or its visual equivalent. "Eye-level medium close-up, shallow depth of field, subject left of center".

- 4. Lighting and color. Direction, quality, palette. "Soft window light from the left, warm amber tones against deep shadow".

- 5. Mood. The emotional register: quiet, tense, celebratory, clinical.

- 6. Background. What sits behind the subject, and how much of it is in focus.

+ Check your current tool set before choosing. Tool state can change mid-session (model switch, credential change), so trust the tools you can see over what this page said at startup. If both surfaces ever appear, prefer the native server tool. When the request is clear, generate directly instead of asking for confirmation; ask only when a required reference image is missing.

- A good prompt reads as a short paragraph, not a list and not a lone sentence. If your prompt fits on one line, it is under-specified, and the model will fill the gaps with whatever it likes.

+ ## Model selection

- ### Rendering text in the image

+ - `gpt-image-2.5-flare` (default): fast, quality above gpt-image-2. Use it for drafts, iterations, and everyday assets.

+ - `gpt-image-2.5-sunburst`: most capable; slower. Use it for precise edits, fidelity to reference subjects and products, dense text or diagrams, and final production assets.

+ - `gpt-image-2`: previous generation; no transparent backgrounds, quality tiers stop at `high`.

- When the image must contain readable text (a sign, a label, a headline), put the exact string in double quotes and state the font style and placement:

+ If Sunburst meets the bar, try the same prompt on Flare and keep Flare when the result still passes.

- A weathered wooden sign above the door reads "OPEN TIL LATE" in hand-painted white serif letters, centered, slightly faded.

+ ## Prompt crafting

- Keep on-image text short. Long passages smear. If the layout matters, say where each string sits.

+ Start from the deliverable, then describe what is visible. Match the prompt's specificity to the user's request:

- ### Anti-patterns

+ - A specific request (exact text, a named layout, a product photo brief) is normalized, not padded. Keep every stated requirement; do not add objects, people, brands, slogans, or story beats the user did not ask for.

+ - A generic request ("a logo for a bakery") gets tasteful concreteness: medium, composition, lighting, palette, materials. Stay within what the request implies.

- - Contradictory instructions. "Photorealistic watercolor" or "minimalist scene packed with detail" forces the model to average two opposing goals, and you get neither.

- - Element overcrowding. Every named object competes for pixels and attention. Past roughly five or six distinct elements, small ones get dropped or mangled. Cut before you add.

- - Style-list collisions. "In the style of anime, oil painting, and pixel art" is three prompts in a trench coat. Choose one style per image and generate variants separately.

+ Cover these when they matter: the deliverable and its use (poster, product shot, UI mockup, diagram, icon); the subject with concrete physical detail; one medium or style, stated plainly; composition and camera (framing, angle, focal length or its visual equivalent); lighting and color; mood; background and how much of it is in focus. For people, describe body framing, gaze, and interaction ("full body visible, feet included", "looking down at the open book").

- ### The revised_prompt loop

+ A short specific prompt is fine. For complex requests, organize the prompt into labeled sections (scene, subject, details, constraints); a descriptive paragraph and a labeled spec express the same intent, so choose whichever is easier to read and update. Request "photorealistic" or "real photograph" explicitly when that is the goal; camera specifications are cues for appearance, not a guarantee of exact optics.

- Both surfaces can return a `revised_prompt`: the prompt the model actually used after its own rewrite. Always read it.

+ ### Rendering text in the image

- 1. Diff it against your intent. Note what the model added, dropped, or reinterpreted.

- 2. Fold the delta into your next prompt explicitly. If the rewrite dropped "overcast sky", put "overcast sky, no direct sunlight" back with more weight. If it added something you dislike, name the exclusion ("no lens flare").

- 3. Regenerate. Treat each round as a conversation with the rewriter, not a fresh roll of the dice.

+ Put the exact string in double quotes, say how many times it appears, and describe its position and typography: `A weathered wooden sign above the door reads "OPEN TIL LATE" once, in hand-painted white serif letters, centered, slightly faded.` Spell unusual words or brand names letter by letter when they matter. Add "no other text" so the model does not invent captions. Keep on-image text short; long passages smear. Use `quality` `medium` or `high` for small text, dense labels, or multiple fonts, then check spelling and legibility in the result.

- ## Model selection

+ ### Anti-patterns

- - `gpt-image-2.5-sunburst` (default): most capable; choose it for precise edits, difficult compositions, and fidelity to references.

- - `gpt-image-2.5-flare`: fastest; choose it for everyday generation and quick iterations.

- - `gpt-image-2`: legacy, previous-generation option.

+ - Contradictory instructions. "Photorealistic watercolor" or "minimalist scene packed with detail" averages two opposing goals, and you get neither.

+ - Element overcrowding. Past roughly five or six distinct elements, small ones get dropped or mangled. Cut before you add.

+ - Style-list collisions. "In the style of anime, oil painting, and pixel art" is three prompts. Choose one style per image and generate variants separately.

+ - Invented content. Extra characters, logos, watermarks, or slogans the user never asked for. State exclusions when the model tends to add them ("no watermark, no logo").

- ## Quality tiers

+ ## Quality, size, and format

- `quality` accepts `low`, `medium`, `high`, `xhigh`, `max`, or `auto` (default). Start with `auto` or a lower tier while exploring, then increase quality for the final image. `xhigh` and `max` are available only on GPT Image 2.5 and incur higher latency and cost. Do not request them with `gpt-image-2`; the API rejects unsupported model/tier combinations.

+ `quality` accepts `low`, `medium`, `high`, `xhigh`, `max`, or `auto` (default). Explore with `auto` or a lower tier; raise it for the final image only while it fixes an unmet requirement, since a higher tier does not guarantee a better image and costs more latency. `xhigh` and `max` exist only on GPT Image 2.5; the API rejects them on `gpt-image-2`.

- ## Image sizes

+ `size` defaults to `auto`. Presets: `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait). Custom `WIDTHxHEIGHT` works when both edges are multiples of 16, the aspect ratio stays within 1:3 to 3:1, neither edge exceeds 3840, and the total pixel count is between 655,360 and 8,294,400 (4K is `3840x2160` or `2160x3840`, not `3840x3840`). Outputs above `2560x1440` are experimental; square images are usually fastest.

- `size` defaults to `auto`. Choose a preset or an arbitrary `WIDTHxHEIGHT` for GPT Image 2 / 2.5. Custom dimensions must satisfy all of these constraints:

+ `output_format`: `png` (default) is lossless and keeps alpha; `jpeg` is the fastest and smallest for photos with no transparency; `webp` is small and keeps alpha. `output_compression` (0-100) applies to jpeg and webp only. The `output_path` extension must match the format or be omitted.

- - Both width and height are divisible by 16.

- - Aspect ratio is between 1:3 and 3:1, inclusive.

- - Neither edge exceeds 3840 pixels.

- - Total pixels are between 655,360 and 8,294,400, inclusive (the upper limit is 3840x2160 or 2160x3840, not 3840x3840).

+ ### Transparent assets

- | Size | Typical use |

- | --- | --- |

- | `auto` | Let the model choose |

- | `1024x1024` | Square preset |

- | `1536x1024` | Landscape preset |

- | `1024x1536` | Portrait preset |

- | `2048x2048` | Larger square |

- | `2048x1152` | 16:9 landscape |

- | `3840x2160` | Maximum-pixel 16:9 landscape |

- | `2160x3840` | Maximum-pixel 9:16 portrait |

+ For logos, stickers, cutouts, and UI icons set `background: "transparent"` with `output_format` `png` or `webp`, and also ask for an isolated subject in the prompt ("isolated on a transparent background, no drop shadow"). A drawn checkerboard is not transparency: after saving, confirm the file has an alpha channel (the result reports `Background: transparent` when the provider confirms it) and inspect edges, hair, glass, and shadows. Repeat the transparent requirement on every later edit of that asset. `gpt-image-2` cannot produce transparency; use a 2.5 model.

## Editing with reference images

- Pass `reference_image_paths` to edit an existing image or use images as visual references. Supply 1-5 local PNG, JPEG, or WEBP files, each at most 50 MB. Paths may be absolute or relative to the current working directory. With references the tool sends an image-edit request; without them it generates from text.

+ Pass `reference_image_paths` to edit an existing image or to use images as references: 1-5 local png, jpeg, or webp files, each at most 50 MB, absolute or relative to the working directory. With references the tool sends an image-edit request; without them it generates from text. Assign each input a role by position ("image 1 is the product to keep unchanged; image 2 is the style reference") and say how they combine.

- Describe the desired END STATE in the prompt, not just a terse change instruction. State what must remain unchanged and what the finished image should contain. When passing multiple references, identify their roles in the same order as the paths.

+ Separate the change from the constraints. Say "change only X" and list what must stay fixed: identity, geometry, layout, lighting, labels, colors, surrounding objects. Describe the desired END STATE, not only the delta.

+ For a local repaint, add `mask_image_path`: a png with an alpha channel the same size as the first reference, where transparent pixels mark the area to repaint. Masking is prompt-guided, so restate the edit and the preserved regions in words too.

```json

{

- "prompt": "The same red fox from the reference, now wearing a knitted blue scarf, in an eye-level wildlife photograph. Preserve its face, fur markings, pose, and forest background. Soft overcast light, muted woodland colors, shallow depth of field; only the scarf is new.",

+ "prompt": "The same red fox from image 1, now wearing a knitted blue scarf, in an eye-level wildlife photograph. Change only the scarf. Preserve its face, fur markings, pose, and forest background; soft overcast light, muted woodland colors, shallow depth of field.",

"model": "gpt-image-2.5-sunburst",

"reference_image_paths": ["art/fox.png"],

"quality": "high",

"size": "2048x1152",

"output_path": "art/fox-with-scarf.png"

}

```

- Read any returned `revised_prompt` after an edit, just as after generation. The client tool includes these in its result text and `details.revisedPrompts`. Compare the rewrite and saved image against the desired end state before another edit, and use a new `output_path` to preserve the source image.

+ Use a new `output_path` so the source stays intact. Only the native server tool returns a `revised_prompt` (the mainline model's rewrite); the client tool reports one in `details.revisedPrompts` only when the provider sends it, so judge the saved image against your request rather than waiting for a rewrite.

- ## Iteration workflow

+ ## Multi-turn refinement

- - Generate one image first. Inspect the result against every clause of your prompt before spending more.

- - Correct deviations by editing the prompt, not by hoping. Name what was wrong and what stays fixed.

- - Batch with `n` only after the prompt is proven. `n` variants of a bad prompt is `n` bad images.

- - Keep the full prompt text in the conversation. It is your reproducibility record: anyone can re-run the exact call later, and you can diff prompt versions when results drift.

+ - Generate one image first and inspect it against every clause of the request before spending more.

+ - Refine one thing per turn: pass the previous output as the next `reference_image_paths` entry, request the single change, and restate the constraints that must survive. "Same style as before" carries context, but restate critical details if the result drifts.

+ - For a recurring character or product, establish one reference image and reuse it in every scene, repeating its defining details.

+ - `n` produces variants of one prompt; distinct assets need distinct calls. Use `n` only after the prompt is proven.

+ - Keep the full prompt text in the conversation as the reproducibility record.

+ ## Check the result

+ Before handing the image over: required text is spelled correctly and legible; identities, product shapes, and labels survived; the edit changed only what was requested; a transparent asset has real alpha rather than a painted background; diagram labels and relationships are correct. Fix a miss by editing the prompt or masking the region, not by regenerating blindly.