Chatgpt Imagegen

ChatGPT Image Generation (OpenAI Image API)

Generate and edit images via the OpenAI Image API using GPT Image models. The OPENAI_API_KEY is loaded automatically from the project root .env; no manual export is required.

Default model

Always use gpt-image-2 unless the user explicitly asks for a different model. The full list:

Quick start

# Text → image (defaults: gpt-image-2, auto size, png)
python skills/chatgpt-imagegen/scripts/generate_image.py \
  "a kawaii red panda wearing sunglasses" panda.png

# Landscape, high quality
python skills/chatgpt-imagegen/scripts/generate_image.py \
  "epic mountain sunrise" mountain.png --size landscape --quality high

# Edit an existing image (inpaint via mask)
python skills/chatgpt-imagegen/scripts/edit_image.py \
  "replace sky with stars" input.png out.png --mask sky_mask.png

# Compose from multiple references
python skills/chatgpt-imagegen/scripts/edit_image.py \
  "group photo of these three people in a modern office" group.png \
  --image person1.png --image person2.png --image person3.png

Both scripts return base64 image data and write it to disk. For n>1 the files become name_1.png, name_2.png, etc.

Parameters

--size

gpt-image-2 accepts any custom resolution under these constraints: each edge ≤ 3840px and a multiple of 16, total pixels between 655,360 and 8,294,400, aspect ratio ≤ 3:1.

The CLI accepts:

--quality

auto (default), low, medium, high. Pricing scales steeply — use low for thumbnails/drafts, high only for final deliverables.

--output-format and --output-compression

png (default), jpeg, webp. Pass --output-compression 0-100 for JPEG/WebP to trade off quality for file size.

The output extension is taken from the file path you pass; pass --output-format only if you want to override it.

--background

opaque | automatic | transparent. Note: gpt-image-2 does not support transparent — use gpt-image-1 or gpt-image-1.5 if a transparent background is required (and use PNG or WebP, not JPEG).

--moderation

auto (default) | low. Pass low for less restrictive filtering on brand/marketing content.

--n

Number of images per call. Files are saved as name_1.ext, name_2.ext, …

Editing modes

edit_image.py covers three patterns:

1. Whole-image edit — pass one input image plus a prompt. The model regenerates the entire image guided by the original.
2. Mask inpainting — add --mask mask.png. The mask must be a PNG with an alpha channel; transparent pixels mark the region to regenerate, opaque pixels are kept.
3. Multi-image composition — pass multiple --image flags (or one positional + multiple --image). The model composes a new image using all references. Useful for combining people, products, or styles.

gpt-image-2 always uses high input fidelity; the --input-fidelity flag exists for older models.

Prompting guidance

Keep prompts descriptive and visual — avoid passive negations ("no clouds") and prefer positive descriptions ("clear blue sky").

GPT Image silently rewrites prompts; the scripts surface the rewritten version as revised_prompt so you can iterate on what the model actually saw.

Common tasks

Logo with transparent background

Transparent output is gpt-image-1.5 / gpt-image-1 only:

python scripts/generate_image.py \
  "minimal flat logo: orange spark icon next to the word 'Acme' in bold sans-serif, on a clean canvas" \
  logo.png \
  --model gpt-image-1.5 --background transparent --output-format png --quality high

High-resolution hero image

python scripts/generate_image.py \
  "panoramic city skyline at dusk, cinematic colour grading" \
  hero.jpeg \
  --size 3840x1280 --quality high --output-format jpeg --output-compression 92

Variation set for A/B testing

python scripts/generate_image.py \
  "social card for a SaaS launch announcement" \
  variant.png --n 4 --size landscape --quality medium

Mask inpainting

Build the mask in any editor (e.g. Pillow, Photoshop) with the area to regenerate set to fully transparent and the rest opaque.

python scripts/edit_image.py \
  "replace the sky with a clear starfield with the milky way" \
  photo.png photo_starry.png --mask sky_mask.png --quality high

Output

Both scripts print saved file paths and any revised_prompt. Pass --json for a machine-readable result:

{
  "model": "gpt-image-2",
  "files": ["panda.png"],
  "revised_prompts": ["A kawaii red panda wearing sunglasses..."],
  "usage": {
    "total_tokens": 4321,
    "input_tokens": 12,
    "output_tokens": 4309
  }
}

Troubleshooting

"OPENAI_API_KEY not set" — confirm the key is in the project root .env file. The scripts auto-load it from there.

"You may need to complete the API Organization Verification" — gpt-image-* models require org verification. Complete it in the OpenAI dashboard.

"Invalid size" — custom dimensions must be multiples of 16, ≤ 3840 per edge, with total pixels in [655,360, 8,294,400] and aspect ratio ≤ 3:1.

Latency — high-quality 4K images can take up to 2 minutes. Don't time out the call; use low/medium while iterating on prompt language.

Transparent background ignored — gpt-image-2 does not support transparent. Switch to --model gpt-image-1.5 --background transparent.

Garbled text in image — text rendering is improved but still imperfect. Quote the text explicitly, keep it short, and re-roll if needed.

Comparison with sibling skills

• gemini-imagegen — Google's Nano Banana Pro. Use when the user explicitly asks for Gemini, or needs Google Search grounding inside the image.
• kie-ai — third-party gateway with GPT-4o, Flux Kontext etc. Use when the user names kie.ai or wants a non-OpenAI GPT image model.
• chatgpt-imagegen (this) — first-party OpenAI Image API. Default for any generic "ChatGPT image" / "OpenAI image" / "DALL-E successor" request.