GPT Image 2 (Replicate)

Generate and edit images with OpenAI GPT Image 2 (openai/gpt-image-2) on Replicate. Strengths: precise instruction-following, accurate in-image text, photorealism, and character consistency — it preserves the identity of reference images at high fidelity, which is ideal for character sheets and storyboards.

Setup

Install dependencies (one-time, usually already present from sibling skills):

pip3 install -r ~/.cursor/skills/gpt-image-2/scripts/requirements.txt

The Replicate API token is shared with the other Replicate skills (avatar-video-reel, brand-asset-studio, bg-music, sound-effects, ...). It is auto-discovered from REPLICATE_API_TOKEN, this skill's config.json, or any sibling skill's config. Only run setup if no valid token is found:

python3 ~/.cursor/skills/gpt-image-2/scripts/setup_key.py YOUR_REPLICATE_API_TOKEN
python3 ~/.cursor/skills/gpt-image-2/scripts/setup_key.py --show   # check current token

Defaults

This skill defaults to --quality high (the model's native maximum — gpt-image-2 has no resolution control, so nothing is ever upscaled) and --aspect-ratio 16:9, matching the intended use for character sheets and storyboards.

Quick Reference

# Text -> image (16:9, highest native quality)
python3 ~/.cursor/skills/gpt-image-2/scripts/generate_image.py \
  "a red origami crane on a weathered wooden table, soft window light" \
  --aspect-ratio 16:9 --quality high -o crane.png

# Edit / compose with reference images (identity preserved automatically)
python3 ~/.cursor/skills/gpt-image-2/scripts/generate_image.py \
  "the same character sitting in a Parisian cafe, reading a book" \
  --ref hero.png -o cafe.png

# Long prompt from a file (best for storyboards)
python3 ~/.cursor/skills/gpt-image-2/scripts/generate_image.py \
  --prompt-file board.txt --aspect-ratio 16:9 -o storyboard.png

# Several variations
python3 ~/.cursor/skills/gpt-image-2/scripts/generate_image.py \
  "logo for a coffee brand called \"EMBER\", bold sans-serif" \
  --aspect-ratio 1:1 --count 4 -o ember.png

Every script prints a JSON object to stdout ending with "files": [...] listing the saved paths.

Workflow 1: Character Reference Sheet

Generate a clean 4-view reference sheet — full-body front (three-quarter), full-body rear, a front head-and-shoulders close-up, and a 90° profile close-up — with locked facial identity and costume, from 1-3 reference pictures of the same character. (Exactly four views: no expression sheet or eye-direction studies, so the canvas isn't flooded with extra faces.)

python3 ~/.cursor/skills/gpt-image-2/scripts/character_sheet.py \
  --ref ref1.png --ref ref2.png \
  --subject "young magician boy, around 10 years old" \
  --description "Slim build, large observant eyes, messy dark-brown hair. Deep midnight-blue robe covered in gold stars, matching pointed wizard hat. Curious, gentle, imaginative." \
  --style "Premium illustrated storybook, hand-painted fairy-tale art, warm magical realism" \
  -o magician_sheet.png

How to use it well:

1. Always pass the reference picture(s) with --ref (repeatable, 1-3). GPT Image 2 preserves their identity automatically.
2. Look at the references and write --subject (a short noun phrase) and --description (build, face, hair, costume, personality). For non-default looks, set --style.
3. The script reproduces the fixed 4-view frame (the four views, lighting, no-text / no-extra-figures rules, consistency mandate). See prompts/character_sheet_framework.md for the full framework and the worked magician example.
4. Defaults are --quality high --aspect-ratio 16:9 (native maximum resolution; nothing is upscaled). Inspect the assembled prompt first with --print-prompt if you want to review/tweak it.
5. To use a completely custom prompt instead of the scaffold, pass --prompt-file path.txt.

character_sheet.py options: --ref (repeatable), --subject, --description / --description-file, --style / --style-file, --bg, --prompt-file, --aspect-ratio (16:9), --quality (high), --count, --pad-color, --output, --print-prompt.

Workflow 2: Product Reference Sheet

Generate a clean 4-view product sheet — front three-quarter, rear straight-on, a front close-up, and a left-side profile close-up — in photorealistic product-photography style, with consistent identity/colour/materials/details across all four views. Optionally pass a product photo with --ref to lock the exact look.

python3 ~/.cursor/skills/gpt-image-2/scripts/product_sheet.py \
  --ref iphone.png \
  --product "iPhone 17 Pro Max in Cosmic Orange" \
  --front "6.9-inch Super Retina XDR display, Dynamic Island, anodized aluminum unibody, Camera Control on the right edge, USB-C on the bottom." \
  --rear "Full-width camera plateau, three 48MP lenses in a triangular pattern, LiDAR + LED flash, recessed Ceramic Shield glass panel, centred Apple logo." \
  --closeup "Dynamic Island housing the front camera, Ceramic Shield 2 glass, precision-machined frame edges, Action + volume buttons on the left." \
  --profile "Camera plateau tapering into the unibody, 8.75mm body, seamless matte aluminum to glass transitions." \
  -o iphone_sheet.png

How to use it well:

1. Write --product (a noun phrase incl. colour/finish) and adapt the four per-view slots (--front / --rear / --closeup / --profile) to what's actually visible in each view. Anything you omit falls back to the generic view instruction.
2. Pass a product photo with --ref (repeatable) to lock the exact look; without it the product is rendered from your description.
3. Set --style to override the default Photorealistic product photography style. (e.g. a clean 3D render or minimalist e-commerce look).
4. The script reproduces the fixed 4-view frame (the four views, lighting, no-text / no-extra-objects rules, consistency mandate). See prompts/product_sheet_framework.md for the full framework and the worked iPhone example.
5. Defaults --quality high --aspect-ratio 16:9. Review with --print-prompt; use --prompt-file for a fully custom prompt.

product_sheet.py options: --ref (repeatable), --product, --front, --rear, --closeup, --profile, --style / --style-file, --bg, --prompt-file, --aspect-ratio (16:9), --quality (high), --count, --pad-color, --output, --print-prompt.

Workflow 3: Storyboard Sheet

Produce a professional multi-panel storyboard sheet (numbered panels with timecodes and shot notes) as one composite image. The prompt is authored per story using the storyboard framework; the script just generates it.

Steps:

1. Read prompts/storyboard_framework.md and build the Phase 1 storyboard image prompt for the story (adapt the framework — title/format header, style, character DNA, visual tone, layout, per-panel scene breakdown, art-direction + format footers). Use the user's exact prompt instead if they provide one.
2. Save the prompt to a file (it is long — 1,200-2,000 words for 15 panels).
3. Generate, passing any character reference sheet with --ref to keep characters consistent across panels:

python3 ~/.cursor/skills/gpt-image-2/scripts/generate_image.py \
  --prompt-file storyboard_prompt.txt \
  --ref magician_sheet.png \
  --aspect-ratio 16:9 --quality high -o storyboard.png

4. After the user approves the storyboard, hand off to the seedance-2 skill, which builds the framework's Phase 2 cinematic video prompt and animates the storyboard sheet into video (passing the sheet as a reference). This skill only produces the Phase 1 image.

Grid layout maps to panel count in the prompt text: 9→3×3, 12→3×4, 15→3×5 (default), 20→4×5. For 9:16 vertical, flip the grid (e.g. 15→5×3) and pass --aspect-ratio 9:16.

Model Capabilities & Constraints

The model has no resolution control, so this skill never upscales — --quality high already gives the maximum resolution gpt-image-2 produces. The only post-processing is:

• 16:9 / 9:16 / 4:3 / 3:4: generated at the nearest native ratio, then the canvas is seamlessly extended to the exact target using the sampled background color (no letterbox bars, no cropping, no upscaling — the content keeps its native resolution; the frame just gains matching-color margin).

generate_image.py Options

Note: generate_image.py defaults --aspect-ratio to 3:2; the character_sheet.py, product_sheet.py, and storyboard flows pass 16:9 explicitly. There is no resolution flag — output is always the model's native maximum.

Prompting Tips (from the model's guidance)

• Be specific: "add soft coastal daylight" beats "make it better".
• Photo language for realism: lens, lighting quality, framing ("shot with a 50mm lens, soft daylight, shallow depth of field").
• Lock what shouldn't change when editing: "change only the lighting; preserve the subject's face, pose, and clothing".
• Put in-image text in "quotes" and describe the typography ("bold sans-serif, centered, high contrast").
• Iterate with small changes rather than rewriting everything.
• Reference multiple images by number: "apply the style from image 1 to the subject in image 2".

Additional Resources

• Character sheet framework + worked example: prompts/character_sheet_framework.md
• Product sheet framework + worked example: prompts/product_sheet_framework.md
• Storyboard (two-phase) framework: prompts/storyboard_framework.md
• Full API details, schema, and post-processing internals: REFERENCE.md