wuyoscar/GPT-Image2-Skill / skills/gpt-image
gpt-image
FlaggedGenerate or edit images through the packaged CLI and Reference Gallery, defaulting to GPT Image 2.6 Flare. Use for posters, typography, reference edits, inpainting, native GIFs, sprite animation, image-led websites, and explicit Image 2/2.5/2.6 requests.
gpt-image
Agent runbook for GPT Image 2 / 2.5 / 2.6 generation/editing. Use the prompt library + packaged CLI. Do not reimplement image API code.
Operating loop
- Classify request and resolve model:
generate,edit,inpaint, ormulti-reference; identify asset type, exact text, aspect ratio, references, safety constraints, and budget/quality. Apply the model-choice rules below before any API call. - Choose the reference path: Image 2 keeps the gallery-first workflow below. For 2.5/2.6, a precise brief needs no reference loading; otherwise choose one short task slice.
- Refine only as needed: preserve the brief. Add a specific gallery case, craft section or template only to fill a concrete gap; do not load them as a bundle for 2.5/2.6.
- Confer when useful: before costly/ambiguous/high-polish calls, present 1–3 matched directions plus planned size/quality; ask at most one concise question at a time. Skip long discussion for precise “generate now” requests with a resolved model.
- Preflight, no side effects: use existing CLI/skill if present. Check command availability (
command -v gpt-image), installed tool lists when the tool manager exists, or the runtime’s own skill registry when available. Do not assume a local home path in cloud/hosted runtimes. - No blind setup: do not reinstall, overwrite skill folders, create/modify
.env, or write API keys unless the user explicitly requested setup. Global/shared installs are opt-in only. - Execute via CLI only: call
gpt-imageorscripts/generate.pywith an explicit--model. Do not create a newgenerate.py, SDK wrapper, or ad-hoc script for normal image requests. - Report: output file path(s), key flags, and one concise refinement suggestion if useful.
Fast path: default 2.6 Flare or an explicit 2.5/2.6 model + precise prompt + “generate now” → preflight and CLI, without a mandatory reference/craft pass. Do not reconfirm an exact valid model.
Model choice and prompt adaptation
| Choice | API model ID | Suggested use |
|---|---|---|
| 2.6 Flare (default) | gpt-image-2.6-flare | Fast generation and editing |
| 2.6 Sunburst | gpt-image-2.6-sunburst | Detailed visual work and precise editing |
| 2.5 Flare | gpt-image-2.5-flare | Fast general generation and drafts |
| 2.5 Sunburst | gpt-image-2.5-sunburst | Precise reference edits and detailed control |
| Image 2 | gpt-image-2 | Existing Image 2 workflows and compatibility |
- With no model specified, or a request for “latest” / “Image 2.6”, use
gpt-image-2.6-flaredirectly without model confirmation. Unqualified “Flare” / “Sunburst” means the 2.6 variant unless an earlier version was already selected for this task. - Preserve an exact model ID or a previously confirmed choice. If an explicit older family is ambiguous (for example “GPT 2.5”), ask which variant; for a misspelled model, clarify rather than silently replacing it. Bare
gpt-image-2.5andgpt-image-2.6are not API IDs. - Always pass the resolved ID through
--model, including the default. The standalone CLI also defaults togpt-image-2.6-flare. Users can pin--model gpt-image-2or a 2.5 model to retain earlier behavior. - Keep model confirmation, cost discussion, and API flags separate from the final image prompt. Use the model-specific reference path below only when it helps the task. Preserve the user's exact text, intended content, reference identity, and edit invariants; obtain confirmation before material prompt changes.
- Generate one image unless the user requested more. Do not silently switch models, change material prompt content, or run multiple model/prompt variants or comparisons. Ask before additional paid variants. For an authorized same-prompt comparison, keep the prompt, size, and quality identical unless the user asks to vary them.
- Consult
references/models.mdwhen parameter support or validation status needs checking. On an invalid-model, access/403, quota, or policy failure, report the failure and stop; do not switch models or rewrite the prompt to retry automatically.
CLI resolution
Preferred call order:
# Existing CLI on PATH
gpt-image --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]
# Installed skill folder; use runtime-provided skill path when available
uv run "$SKILL_DIR/scripts/generate.py" --model MODEL_ID -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]
# Direct transient CLI when the user requested setup/one-off CLI execution
uvx --from git+https://github.com/wuyoscar/gpt_image_2_skill gpt-image --model MODEL_ID -p "PROMPT" [options]
scripts/generate.py is a launcher: repo-local src/gpt_image_cli → installed gpt-image → PATH gpt-image → transient uvx/uv fallback.
Image to animation or website
Match the deliverable, not just the first image:
- Native GIF: use
--format gif, optional--frames(2-16) and--frame-duration(20-2000 ms). Size defaults toautofor GIF. Inspect all frames and actual playback. Do not use masks or compression with GIF. - Sprite sheet to GIF: generate one evenly divided grid with a fixed camera, scale, anchor and explicit cell order, then run
gpt-image animate --sheet sheet.png --columns 4 --rows 2 --duration 160 -f loop.gif --preview player.html. This local step needs no key and makes no API calls. It slices existing frames; it does not invent motion from a still or fix registration errors.--ping-pong,--margin,--gutterand--counthandle playback and spacing. Inspect alpha, every cell, loop seam and jitter. - Image-led website: generate visual assets, then build real HTML/CSS/JS around them. Keep controls and readable interface text in HTML. Test clicks, pause/reduced-motion behaviour, mobile layout and asset paths. A screenshot is not a working website.
Read creative workflows in a full repo/plugin checkout. In a standalone skill folder, use references/models.md and CLI --help / animate --help; the examples are also at https://github.com/wuyoscar/gpt_image_2_skill/blob/main/docs/creative-workflows.md.
Key and cost rules
- CLI reads
OPENAI_API_KEYfrom process env, then.env, then~/.envwithout overriding existing env; successful API calls may bill the user’s OpenAI account. - If host/runtime has native platform-managed image generation and the user wants that path, use the host tool instead of this CLI.
- If
OPENAI_API_KEYis unset, report missing key or use host-native generation when requested; do not write secrets. - If user wants to avoid local-key use, respect
unset OPENAI_API_KEY; if a key exists in.env/~/.env, tell them to remove/rename it for the session rather than working around it. - Never print secret values.
Flags
| Flag | Values | Use |
|---|---|---|
-p, --prompt | string | Required prompt/edit instruction |
-f, --file | path | Output path; auto-named if omitted |
-i, --image | repeatable path | Use edits endpoint; supports multiple references |
-m, --mask | PNG path | Inpaint with alpha mask; requires -i |
--model | Exact ID from the model table | Default 2.6 Flare; agent passes the resolved ID explicitly |
--size | 1k, 2k, 4k, portrait, landscape, square, wide, tall, or literal | Canvas size |
--quality | low, medium, high, auto; 2.5/2.6 also xhigh, max | Cost/quality dial; check model-specific limits |
-n, --n | integer | Number of images |
--background | auto, opaque; 2.5/2.6 also transparent | Transparency requires PNG or WebP, not JPEG |
--input-fidelity | low, high; omitted by default | Edit-only; explicit 2.5/2.6 values are forwarded to the API, not assumed supported |
--moderation | auto, low | Generation moderation setting |
--format | png, jpeg, webp, gif | GIF uses 2.6; default remains PNG |
--frames / --frame-duration | 2-16 / 20-2000 ms | Native GIF only; API defaults 9 / 200 |
--compression | 0-100 | JPEG/WebP compression |
--user | string | Optional end-user identifier |
Quality starting points (not guarantees; keep the user's agreed setting). For 2.5/2.6, these take precedence over fixed quality advice in older craft references:
low: cheap drafts and broad exploration; multiple variants require user authorization.medium: normal exploration, style probing, balanced cost.high: CLI default and a candidate for final assets, dense text, diagrams and UI. On 2.5/2.6, evaluate against the task requirements; do not assumemediumfails or a higher setting always wins.xhigh/max: 2.5/2.6 options for higher-quality work; discuss the cost trade-off before increasing an already agreed quality. Do not use them automatically for budget-conscious requests.
Size policy:
- default/social square:
1k/1024x1024 - poster/mobile/beauty:
portrait - landscape/gameplay/photo:
landscape - print/paper figure:
2k - widescreen hero:
4k - vertical story/banner:
tall
Endpoint routing
| Mode | Trigger | Endpoint |
|---|---|---|
| Text-to-image | no -i | /v1/images/generations |
| Reference edit | one or more -i | /v1/images/edits |
| Inpaint | -i + -m | /v1/images/edits with mask |
Surface API errors verbatim enough for debugging; exit codes: 0 success, 1 API/refusal, 2 bad args/missing key.
Reference loading
- Image 2: open
references/gallery.md, then one matchingreferences/gallery-*.mdcategory and its actual prompt text. Read only relevant sections ofreferences/craft.mdor the historicalreferences/openai-cookbook.mdwhen needed. - Image 2.6: use
references/models.mdfor current compatibility and verification status. For prompt inspiration, reuse a relevant 2.5 task slice below; these are historical guidance, not 2.6-verified examples. - Image 2.5: no mandatory references for a precise brief. If guidance is needed, choose one directly:
references/openai-image-2.5-generation.md(photo/product/illustration),references/openai-image-2.5-layout-and-text.md(text/UI/diagrams/panels), orreferences/openai-image-2.5-editing.md(references/masks/translation). - Other questions:
references/openai-image-2.5.mdis an optional index;references/openai-image-2.5-migration.mdcovers migration/comparison;references/models.mdowns current API parameters and validation status. - Extra inspiration only: gallery cases, a targeted craft section, or
references/templates-gpt-image-2.5.md(community adaptations, not verified outputs). Do not preload them or the old Cookbook for 2.5/2.6.
Load the smallest useful slice, not both model routes. Add a second task slice only for a genuine hybrid. Historical examples do not override current API notes or the user's model/settings.
Verification
- Before API call: check the resolved model and explicit
--model, endpoint mode, size, quality, output path, and required reference/mask files. Omit--input-fidelityunless explicitly needed; do not assume 2.5/2.6 always uses or acceptshigh. - After CLI call: report path(s) printed by the CLI and surface stderr on failure.
- For edits/inpaints: verify
-ipaths exist; verify-mexists when used.
Preserve Curated vs Author + Source metadata when adapting examples. Add new collected prompts to the Reference Gallery before README promotion.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |