/gpt-image

name: gpt-image
description: Execute image generation, editing, and chroma-key transparent-background workflows with GPT Image 2 / gpt-image-2 through the bundled scripts. Use when GPT Image is the selected backend and a supplied prompt or edit instruction must be executed for text-to-image generation, reference-image editing, multi-reference editing, masked inpainting, or chroma-key background removal. Treat the supplied prompt as authoritative; this skill does not search prompt galleries, choose art direction, or perform general prompt planning.

GPT Image Executor

Execution-only runbook for GPT Image generation and editing. Use the packaged CLI; do not reimplement image API code.

Responsibility boundary

• Accept the prompt or edit instruction produced by the user or an upstream workflow.
• Do not browse prompt examples, invent an art direction, compare creative concepts, or rewrite the prompt semantically.
• Apply only backend-required formatting and parameter mapping. If a required execution input is missing or contradictory, ask one concise question.
• Generate or edit images only through this skill's packaged CLI.
• Do not create a new SDK wrapper or ad-hoc generation script unless the user explicitly asks to modify this repository.

Operating loop

1. **Classify operation**: `generate`, `edit`, `inpaint`, `multi-reference`, or chroma-key background removal. 2. **Preflight without mutation**: verify the CLI, Python 3.11+, required packages, input files, output destination, and credential availability. 3. **Map execution parameters**: pass the supplied prompt unchanged in meaning; select endpoint flags, size, quality, count, format, and output path from explicit requirements or conservative defaults. 4. **Execute via CLI**: call the packaged command directly. 5. **Report**: return output path(s), material flags or defaults, and actionable API errors.

Requirements

• Python 3.11+ with `openai>=1.55`.
• Pillow for chroma-key background removal only.
• `OPENAI_API_KEY` for the default OpenAI endpoint. Calls may incur API charges.
• Do not reinstall dependencies, overwrite skill folders, create or modify `.env`, or write API keys unless the user explicitly requests setup.

CLI

python "$SKILL_DIR/scripts/src/gpt_image_cli/cli.py" -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]

Key and cost rules

• The CLI reads `OPENAI_API_KEY` from process env, then `.env`, then `~/.env`, without overriding an existing environment value.
• Set `OPENAI_BASE_URL` in the environment to use a compatible endpoint. The OpenAI API is the default.
• If the host has platform-managed image generation and that is the selected backend, use the host capability instead of this CLI.
• If `OPENAI_API_KEY` is unset, report it; do not write or print secrets.
• Respect a user's request to avoid local-key use. Do not work around their credential choice.

Flags

| Flag | Values | Use | |---|---|---| | `-p, --prompt` | string | Required prompt or 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` | default `gpt-image-2` | Image model | | `--size` | `1k`, `2k`, `4k`, `portrait`, `landscape`, `square`, `wide`, `tall`, or literal | Canvas size | | `--quality` | `low`, `medium`, `high`, `auto` | Cost and quality | | `-n, --n` | integer | Number of images | | `--background` | `auto`, `opaque` | Background behavior; use `opaque` for chroma-key removal | | `--remove-background` | flag | After the API response, run the bundled chroma-key remover on every output and replace each keyed PNG/WebP with its alpha result | | `--moderation` | `auto`, `low` | Generation moderation setting | | `--input-fidelity` | `low`, `high` | Edit fidelity; dropped for `gpt-image-2`, which rejects it | | `--format` | `png`, `jpeg`, `webp` | Output encoding | | `--compression` | `0-100` | JPEG or WebP compression | | `--user` | string | Optional end-user identifier |

Quality policy:

• `low`: cheap drafts, broad exploration, many variants.
• `medium`: normal exploration, style probing, balanced cost.
• `high`: final assets, Chinese text, posters, diagrams, UI, paper figures, dense labels.

Size policy:

• default or social square: `1k` / `1024x1024`
• poster, mobile, or beauty: `portrait`
• landscape, gameplay, or photo: `landscape`
• print or paper figure: `2k`
• widescreen hero: `4k`
• vertical story or banner: `tall`

Timeout policy:

• `1k`, `portrait`, `landscape`, or `square`: **180000 ms** (3 minutes)
• `2k`, `4k`, or multi-image batches (`-n > 1`): **360000 ms** (6 minutes)

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 enough of API errors for debugging. Exit codes are `0` for success, `1` for API error or refusal, and `2` for invalid arguments or a missing key.

Transparent-background workflow

Use chroma-key removal for transparent assets. The only supported path is `--background opaque --remove-background`.

Default sequence:

1. Choose a key color unlikely to appear in the subject: default `#00ff00`, use `#ff00ff` for green subjects, and avoid `#0000ff` for blue subjects. 2. Append only the following execution constraints to the supplied prompt, replacing the key color when needed:

Create the requested subject on a perfectly flat solid #00ff00 chroma-key background for background removal.
The background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation.
Keep the subject fully separated from the background with crisp edges and generous padding.
Do not use #00ff00 anywhere in the subject.
No cast shadow, no contact shadow, no reflect