Generate Image

Requires GEMINI_API_KEY environment variable and uv package manager.

Workflow

1. Understand — Determine mode (t2i, i2i, multi-reference), gather parameters (model, aspect ratio, resolution, output path). If the prompt requires precise execution (specific pose, asymmetric framing, exact crop), default to --batch 3 or --batch 4 and surface this to the user — image generation is stochastic and precise directives hit ~50% per seed. Exit: mode, parameters, and batch size are clear. 2. Craft prompt — Default to the minimal prompt that can carry the intent: t2i uses narrative prose; i2i/multi-reference uses a reference block plus the minimal directive. Apply the Core checklist (always, for the matching mode). Reach into the Escalation toolkit only on a known-hard signature — a detail/geometry-fidelity shot — or after a batch shows drift; then add only the specific lock for the attribute that is drifting, not the whole kit. Over-constraining a simple edit degrades it as surely as under-specifying a complex one. Exit: prompt written, Core items satisfied, escalation tools added only where a signature or observed drift justifies them. 3. Confirm — Show the user the exact prompt, input images (if any), model, resolution, aspect ratio, and batch size. Ask for confirmation. Exit: user approves. 4. Generate — Run the script with confirmed parameters. Exit: images are saved and displayed. 5. Iterate — Present results and evaluate against intent before offering refinements. Evaluation order by mode: t2i — subject correctness, composition, style fidelity. i2i edit — the changed element looks right, nothing else changed. Multi-reference composition — the primary transferred attribute matches its source reference FIRST (for a detail shot, the construction geometry — width, edge shape, count, angle), secondary consistency (identity, environment) holds SECOND, staging (lighting, composition, framing) THIRD. Decide what's primary per task. Cherry-pick the winning frame from the batch rather than re-prompting for consistency past ~75%. Exit: user is satisfied or moves on.

Default Output & Logging

When the user doesn't specify a location, save images to:

~/Documents/generated images/

Every generated image gets a companion .md file with the prompt and model used (e.g., logo.png → logo.md).

When gathering parameters (aspect ratio, resolution), offer the option to specify a custom output location.

---

Core Prompting Principle

Describe scenes narratively, not as keyword lists. Gemini's language model parses prose with full semantic understanding — narrative prompts encode spatial relationships, mood, and intent that comma-separated tags cannot express. Tag-style prompts lose compositional meaning and produce generic results.

Bad:  "cat, wizard hat, magical, fantasy, 4k, detailed"

Good: "A fluffy orange tabby sits regally on a velvet cushion, wearing an ornate
       purple wizard hat embroidered with silver stars. Soft candlelight illuminates
       the scene from the left. The mood is whimsical yet dignified."

Describe positively, never via negation. Every concept named in a prompt biases the output toward that concept — even when preceded by "not", "no", or "do not". Diffusion models condition on tokens regardless of polarity. To exclude X, either (a) name a positive alternative that fills the same role, or (b) scope the prompt so X has no place to land.

Bad:   "A clean studio backdrop. No warm tones, no cream, no beige, no tan."
Good:  "A clean cool-neutral gray studio backdrop with subtle blue undertones."

Bad:   "A headshot with no harsh shadows on the face, no distracting background."
Good:  "A headshot on a clean neutral gray backdrop, even soft frontal fill light
        that flatters the face."

This rule applies everywhere in the skill — t2i prompts, i2i directives, reference role descriptions, and framing instructions.

Name sources explicitly — leave no ambiguity in references. Every element in the prompt should trace to a specific source: "the man from Image 2" not "this man"; "the shirt from Image 3" not "the shirt". Ambiguous references bind to whichever source the model weights most, which is never reliably the right one. This isn't about over-describing — don't re-describe what the reference already shows. It's about making each reference point to exactly one source.

A useful formula: [Subject] doing [Action] in [Context]. [Camera/Composition]. [Lighting]. [Style]. [Constraint]. Not every prompt needs every element — match detail to intent. If the user has a specific vision, be prescriptive (exact descriptions); if exploring, be open (general direction, let the model decide details). Ask if unclear.

Advanced Prompting Techniques

Hyper-specificity: Be precise about quantities, positions, and attributes. "Three red apples arranged in a triangle on a wooden table" outperforms "some apples on a table." Every vague word is a degree of freedom the model fills arbitrarily.

Context and intent: State the purpose. "A hero image for a coffee brand landing page" produces different results than "a photo of coffee" even if the visual subject is the same, because intent shapes composition, mood, and framing.

Step-by-step instructions: For complex scenes, break the prompt into sequential directives. "Start with a wide desert landscape. Place a lone figure walking left-to-right in the lower third. Behind them, a massive sandstorm approaches from the right."

Exclusion via positive constraint: When something must be absent from the output, do not name it under a negation. Either name a positive alternative ("clean unbranded surface" instead of "no logos") or scope the scene so the unwanted element has no place to land ("a closed laptop on the desk" makes a screen impossible to render). Naming X under "no X" makes X more likely, not less.

Camera control: Specify shot type (extreme close-up, medium shot, aerial), lens (fisheye, telephoto), and camera angle (low angle, bird's eye, Dutch angle) to control framing precisely.

Editing with reference images follows different principles — see references/editing-guide.md.

---

Key Editing Principles

Editing prompts direct changes rather than describing scenes. Point to what the model can see; describe only what it cannot. Specify intentionally — every adjective, color word, or preservation clause beyond the minimum competes with the reference image and degrades fidelity. The reliable shape is a reference block plus one Replace directive — the verb's implicit scope handles preservation, no stop clause needed. Details in editing-guide.md.

For multi-reference work (3+ images), use per-reference role assignment: one sentence that assigns each reference its specific contribution ("the facade from Image 2; the car from Image 3; the sky and lighting from Image 1") — see editing-guide.md "Per-Reference Role Assignment".

Base image goes first in --input — it becomes Image 1 in the prompt. Gemini numbers images sequentially from input order. Reference block labels must match input order exactly.

Names invoke aesthetics directly — referencing "shot on Kodak Portra 400" produces its characteristic look more reliably than describing warm skin tones and pastel highlights.

---

References

Load the relevant reference during prompt crafting (workflow step 2):

• references/capability-patterns.md — mode-specific tips for photorealistic scenes, product photography, logos, stylized illustration, text rendering, and grounding
• references/editing-guide.md — edit grammar, reference blocks, directive structure, image ordering, semantic masking, character consistency
• references/style-reference.md — named aesthetics lexicon (film stocks, cameras, studios, artists, movements)

---

Configuration

Model Selection

Default to Nano Banana for most requests. Use Nano Banana Pro when the user explicitly asks for maximum quality or when Nano Banana results need refinement.

Aspect Ratios

Both models: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 Nano Banana only: 1:4, 4:1, 1:8, 8:1

Resolutions

• 0.5K (~512px) — fast preview (Nano Banana only)
• 1K (~1024px) — default, fast
• 2K (~2048px) — high quality
• 4K (~4096px) — maximum detail

Defaults: 1K resolution, batch 1, aspect ratio auto-detected from base image (first input, or 1:1 if no images). Use 0.5K for quick previews and iteration (Nano Banana only). Use 2K for higher quality requests, 4K only when high detail is explicitly needed.

Thinking Mode (Nano Banana only)

Nano Banana supports controllable thinking levels that improve complex prompt interpretation:

• minimal (default) — fastest, suitable for straightforward prompts
• low/medium — balanced reasoning for moderately complex scenes
• high — maximum reasoning for complex multi-element compositions, precise text rendering, or intricate spatial layouts

Use --thinking high when the prompt involves precise spatial relationships, multiple text elements, or detailed composition requirements. For i2i editing, thinking mode also helps with multi-reference composition (3+ images), precise text/sign placement on existing scenes, and complex spatial edits where element positioning matters.

---

Script Usage

One unified script handles all modes: t2i, i2i, and multi-reference composition. Nano Banana is the default model.

# Text-to-image (t2i) — uses Nano Banana by default
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png

# Nano Banana Pro model
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "A serene mountain lake at dawn" --output landscape.png --model pro

# Image-to-image editing (i2i)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Make it sunset colors" --input photo.png --output edited.png

# Multi-reference composition
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Combine the cat from image 1 with the background from image 2" --input cat.png --input background.png --output composite.png

# With options (aspect ratio, resolution, thinking, batch, grounding, format)
uv run ${CLAUDE_PLUGIN_ROOT}/skills/generate-image/scripts/generate.py --prompt "Logo for 'Acme Corp'" --output logo.png --aspect 1:1 --resolution 2K --thinking high

Script Options

The script auto-detects resolution and aspect ratio from input images when flags are omitted, and automatically resizes large inputs (>2048px) before sending to the API.

---

Pre-Generation Checklist

Core items are the floor — apply them to every prompt of the matching mode. The Escalation toolkit is opt-in: skip it entirely for simple t2i and single-element edits. Reach in only on a known-hard signature (a detail/geometry-fidelity shot) or after a batch shows drift — and then add only the lock for the attribute that is actually drifting. Each added constraint costs fidelity on everything else, so escalation scales with how many independent things can drift, not with how ambitious the prompt is.

Core — t2i (always)

• [ ] Narrative description (not keyword list)?
• [ ] Positive framing throughout — no "no X" / "not X" / "do not X" clauses anywhere in the prompt?
• [ ] Camera/lighting details for photorealism?
• [ ] Text in quotes, font style described? (if the image has text)
• [ ] Aspect ratio appropriate for use case?
• [ ] Model choice appropriate? (Nano Banana default; Nano Banana Pro for max quality)
• [ ] Thinking level set for complex prompts? (Nano Banana only)
• [ ] Batch size matches precision needs? (--batch 3 or --batch 4 for precise pose / framing / asymmetric directives)

Core — i2i / multi-reference (always)

• [ ] Reference block at start of prompt labeling each image's role?
• [ ] Reference roles positive-only — lists what to USE from each ref, never what to ignore? (see editing-guide.md "Reference Block")
• [ ] Minimal directive pattern? (Reference block + one Replace directive — no "do not change anything else" stop clause, no decorative preservation clauses)
• [ ] Positive framing throughout the directive? (no negation anywhere, including locks and composition clauses)
• [ ] Base image first in --input (Image 1), and prompt labels match input order? (mislabeled roles cause character drift)
• [ ] Only one change per prompt? (split competing directives into sequential passes)
• [ ] When extracting/transferring elements: explicitly named each element rather than generic "outfit/object from image X"?
• [ ] One reference carrying an element you need to preserve while another reference could compete with it? → add CRITICAL — [element] proactively: assign the source reference explicitly ("Image 1 is the sole identity source. Image 2 is scoped to [attribute] only."). Do not wait for drift — role competition defeats text directives silently.
• [ ] No color labels competing with reference image? (color words override visual reference — see editing-guide)
• [ ] Base image has minimal accessories that could contaminate? (bags, hats, sunglasses bleed into output)
• [ ] Reference count within model limits? (Nano Banana: 14, Nano Banana Pro: 11)
• [ ] For 3+ references: per-reference role-assignment sentence? (one sentence assigning each image its contribution — see editing-guide.md "Per-Reference Role Assignment")
• [ ] For photorealistic human shots: skin & finish locked? (the one near-universal CRITICAL section — generative skin drifts to plastic/retouched)

Escalation toolkit — reach for only on a hard signature or observed drift

• [ ] An attribute (identity, lighting/color, orientation, drape) drifting across the batch? Lock that specific attribute in its own ## CRITICAL — section, positively phrased — without over-constraining the stable ones. (see editing-guide.md "Constraint Locking with CRITICAL Sections")
• [ ] Detail shot whose construction won't hold? Geometry lock via per-attribute enumeration, not generic "match exactly". (see capability-patterns.md "Geometry Lock for Detail Shots")
• [ ] Nano Banana + --thinking high with 3+ references and weak adherence? Add the inventory preamble. ("Silently inventory the design-critical details: ...")
• [ ] Follow-up shot from the same set? Continuity assertion. ("from the same set as Image N: same subject, same setting, same light" — see editing-guide.md "Continuity Assertion")
• [ ] Campaign with a locked hero image? Collapse to two-input form — hero as bundle-source + the single new-attribute reference. (see editing-guide.md "Single-Reference Collapse")

Capability Patterns

Mode-specific prompting tips. Load the relevant section during prompt crafting (workflow step 2).

---

Photorealistic Scenes

Think like a photographer: describe lens, light, moment.

• Specify camera (85mm portrait, 24mm wide), aperture (f/1.8 bokeh, f/11 sharp throughout)
• Describe lighting direction and quality (golden hour from camera-left, three-point softbox)
• Include mood and format (serene, vertical portrait)

Product Photography

• Isolation: Clean white backdrop, soft even lighting, e-commerce ready
• Lifestyle: Product in use context, natural setting, aspirational but authentic
• Hero shots: Cinematic framing, dramatic lighting, space for text overlay

Logos & Text

• Put text in quotes: 'Morning Brew Coffee Co'
• Describe typography: "clean bold sans-serif with generous letter-spacing"
• Specify color scheme, shape constraints, design intent
• Iterate with follow-up edits for refinement

Stylized Illustration

• Name the style: "kawaii-style sticker", "anime-influenced", "vintage travel poster"
• Describe design language: "bold outlines, flat colors, cel-shading"
• Include format constraints: "white background", "die-cut sticker format"

Text Rendering

Nano Banana has advanced text rendering capabilities. For best results:

• Put all text in single quotes within the prompt
• Describe font characteristics: weight, style, size relative to the image
• Specify text placement: "centered at the top," "bottom-right corner"
• For multiple text elements, describe each separately with position
• Use --thinking high for complex multi-line text or precise typography

Google Search Grounding

Enable with --grounding flag when real-time data helps (weather visualizations, current events infographics, real-world data charts).

Image search grounding (Nano Banana only): Add --image-grounding alongside --grounding to enable image search results as additional visual context. Useful when the model needs to reference real-world visuals (product designs, architectural styles, specific locations).

---

Best Practices

Hyper-Specificity

Vague prompts produce generic results. Every unspecified attribute becomes a random variable.

Vague:    "A woman in a park"
Specific: "A 30-year-old woman with shoulder-length auburn hair sits cross-legged
           on a green wool blanket in a sun-dappled oak grove, reading a hardcover
           book. Late afternoon golden hour, shallow depth of field at f/2.0."

Quantities, colors, materials, spatial positions, and named objects all reduce variance.

Context & Intent

State what the image is for. Purpose shapes composition, mood, and framing decisions.

Generic:     "A flat white coffee on a marble counter"
With intent: "A hero image for an artisan coffee brand's homepage — a flat white
              in a handmade ceramic cup on a marble counter, steam rising, soft
              morning light from the left, negative space on the right for text overlay"

Step-by-Step Instructions

Complex scenes benefit from sequential directives rather than a single compound sentence.

"Start with a wide establishing shot of a misty fjord at dawn.
 In the foreground, place a wooden dock extending from the lower left.
 A small red sailboat is moored at the dock's end.
 Mountains fill the background, their peaks just catching the first golden light.
 The water is perfectly still, creating mirror reflections."

Positive Framing for Exclusions

Naming a concept under negation ("no X", "not X") biases the output toward X — diffusion models condition on tokens regardless of polarity. To exclude something, name a positive alternative that fills the same role, or scope the scene so the unwanted element is physically not there.

Bad:   "A professional headshot on a neutral gray backdrop.
        No distracting background elements, no visible logos or text,
        no harsh shadows on the face."

Good:  "A professional headshot on a clean seamless gray backdrop,
        even soft frontal fill light that flatters the face, the
        wall-to-floor falloff smooth and uncluttered."

The Good version states what's there, not what isn't. "Clean seamless" implies absence of distraction. "Even soft frontal fill" implies absence of harsh shadows. The model never has to suppress a named concept.

Camera Control

Photographic terms give precise control over framing and perspective.

• Shot types: extreme close-up, close-up, medium shot, full shot, wide shot, extreme wide shot
• Angles: eye level, low angle (heroic), high angle (diminishing), bird's eye, worm's eye, Dutch angle
• Lenses: fisheye (distortion), wide-angle (expansive), normal 50mm (natural), telephoto (compression), macro (tiny subjects)
• Movement metaphors: "tracking shot following the subject," "slow dolly-in," "crane shot rising above"

---

Fashion & Garment Editing

Garment swaps and fashion compositing require specific techniques beyond generic i2i editing.

Base Image Selection

The base image matters as much as the prompt. Choose bases where:

• The garment being replaced is a contrasting color to the target (white base → olive swap, not olive → olive)
• The model/mannequin has minimal accessories (no bags, berets, sunglasses that bleed into output)
• The composition already has the target framing (Gemini cannot re-frame — see editing-guide.md)

Garment Swap Prompts

Use the reference block to label the image's role. Let the reference image carry color, cut, and texture — naming those attributes in the directive creates competing signals against the reference pixels.

Image 1: Base scene
Image 2: Reference shirt

Replace only the shirt on the mannequin with the blouse from Image 2.

No stop clause — Replace already scopes the edit in place. See editing-guide.md "Minimal Directive Pattern".

Texture and Fabric

For premium fabric rendering, name the texture type without describing the color: "authentic linen texture with natural slub weave and organic drape." This gives the model rendering instructions while letting the reference image control color fidelity.

Multi-Step Fashion Edits

When changing outfit plus accessories or garment plus signage, split into passes (see editing-guide.md "Multi-Pass Editing"). Common two-step patterns:

• Garment swap first, then sign/easel text edit
• Outfit replacement first, then accessory adjustment
• Subject compositing first, then pose refinement

Multi-Reference Fashion Directive

The fashion instance of Per-Reference Role Assignment (editing-guide.md). When composing a full look from a face reference, separate garment references, and a lighting/backdrop plate, assign each reference its contribution in one positive sentence:

Perfectly replicate the exact features of the man's face from Image 2; the exact
shirt, trouser, belt, and shoe construction and color from Image 3; the cuff and
collar construction from Images 4 and 5; the cotton weave and sheen from Image 6;
and the lighting, backdrop, and photographic finish from Image 1.

Each image gets a positively-named job, attributes are enumerated per image (not "the outfit"), and replication verbs ("perfectly replicate", "exact") carry positive intensity with zero negation. For the structural breakdown, see editing-guide.md "Per-Reference Role Assignment".

Detail Shots (fashion instance of Single-Reference Collapse)

This is the fashion application of Single-Reference Collapse (editing-guide.md). Once a hero image is locked for a campaign, every follow-up detail shot collapses to two-input form: the hero PNG as Image 1 (in this campaign the hero front shot was the bundle-source — it encoded the model's identity, the studio lighting, color science, backdrop, and wardrobe color), plus the single raw construction reference for the detail being shown (cuff macro, collar close-up, weave swatch). The character sheet and the separate lighting reference get dropped — the hero already carries what they contributed.

Inputs (order matters — base first):
  Image 1: final/<colorway>/front.png        ← bundle-source for everything locked this campaign
  Image 2: raw/<colorway>/Cuff.jpg           ← scoped to the construction detail being shown

Settings: --model nano-banana --thinking high --resolution 2K --batch 3 --aspect 3:4
Expected yield: 2/4 keepers (detail crops are simpler than full-body)

(Adapt directory names to your campaign layout — `final/` and `raw/` above are MaisonX conventions.)

Which reference is the bundle-source is a per-campaign choice, not a fixed rule — here it was the hero front shot. This two-input form outperformed the original six-reference setup for detail shots because there were fewer competing signals. Anchor the detail shot to the bundle-source with a continuity assertion (editing-guide.md) and lock the construction with geometry enumeration (below).

Geometry Lock for Detail Shots

The fashion instance of Geometry Enumeration (editing-guide.md). Generic "match Image 2 exactly" does not preserve specific geometric attributes — the model interprets "exactly" aspirationally and width, edge shape, button count, and point spread all drift seed-to-seed. To lock garment geometry, enumerate each attribute explicitly in a dedicated CRITICAL — Geometry match section, named positively.

Canonical attributes by garment region:

Phrase the attributes in positive form. "Sharp 90° corners" not "not rounded". "Single button at the wrist edge" not "no double cuff". The rule from the Core Prompting Principle applies: every concept named under negation biases toward that concept.

Reference Orientation Lock

The fashion instance of scope completeness (editing-guide.md "Reference Block"). Scoping a reference to "construction only" can strip too much — Gemini drops the arm rotation, body angle, or camera direction that came baked into the reference's framing. The fix is to scope the reference to multiple positive attributes: construction AND orientation. Example for a back-of-wrist cuff shot:

Image 2 — Cuff construction and orientation reference. Silently inventory:
- The exact cuff geometry: [enumerated attributes above]
- The arm orientation: the model's torso is rotated so the back of the arm,
  the back of the wrist, and the back of the hand face the camera. The cuff
  button visible to camera sits on the outside of the wrist.

Two positively-named contributions from one reference. The directive sentence that follows must echo both: "The cuff construction and the back-of-wrist orientation come from Image 2."

---

Working from Video References

When using reference videos as starting points for image generation (e.g., adapting an existing ad concept):

Frame Extraction

Use a two-pass approach with ffmpeg:

1. Scene detection — Find transition timestamps:

ffmpeg -i input.mp4 -vf "select='gt(scene,THRESHOLD)',showinfo" -vsync vfr -f null - 2>&1 | grep "pts_time"

2. Targeted extraction — Extract a single frame at a specific timestamp:

ffmpeg -y -ss <TIMESTAMP> -i input.mp4 -frames:v 1 -update 1 output.png

Start with threshold 0.3 and lower to 0.15 if too few frames are detected. Fashion videos with smooth transitions (car wipes, camera pans) typically need the lower end.

Key Considerations

• Scene detection fires on visual composition changes, not semantic content changes. In videos where transitions are masked by passing objects, scene detection catches the transition itself, not the clean reveal after it. A second probe pass between detected timestamps is necessary.
• Always check ffprobe metadata first (ffprobe -v quiet -print_format json -show_format -show_streams) to understand resolution, fps, and duration.
• Name extracted frames descriptively (e.g., outfit_1_blue_denim.png) rather than by frame number — self-documenting folders save time during editing.

Editing & Composition Guide

Load this reference when the user provides input images for editing or multi-reference composition. These principles do not apply to text-to-image generation.

---

Core Principle

Connect the dots, don't describe. Reference images provide the visual context. The prompt's job is to tell the model what goes where — not re-describe what the model can already see. Over-describing creates competing signals between text and image that degrade output quality.

Bad:  "Replace the front figure with a woman who has light fair skin, delicate oval
       face, dark sunglasses, dark brown headscarf, sleeveless beige linen dress..."

Good: "Replace the front figure with the woman from image 3"

The Pointing vs Naming Boundary

Point to reference images for elements that will be used whole (a face, a background, a scene). Explicitly name elements when extracting or transferring parts from a reference to a different context, because generic references like "outfit from image 2" don't tell the model which visual elements to isolate from surrounding context.

Bad:    "Replace the clothing with the outfit from image 2"
Better: "Replace the clothing with the linen button-up shirt and wide-leg trousers from image 2"

Name structural attributes (garment type, cut, fabric) when extracting parts from a reference — but never colors. Structural names tell the model which elements to isolate from the reference's surrounding context; colors belong to the reference image's pixels (see Color Labels Override Visual References below).

---

The Edit Grammar

Reference Block

Start multi-image edit prompts with a reference block that explicitly labels what each image represents. This disambiguates image roles before the directive.

Image 1: [base — canvas being edited]
Image 2: [reference role/description]
Image 3: [reference role/description]

[Main directive]

Roles stay short — one phrase. Don't enumerate what the reference image contains in the label ("Image 2: Reference outfit — white linen blouse and camel trousers"). That re-describes what the pixels already show; the redundancy creates competing signals against the reference.

Scope references positively, never via exclusion. Phrases like "ignore the person, pose, face, and background" or "the model in this image is not retained" name the very elements you want the model to disregard, pulling them back into attention. Instead, list only what to use from each reference. The model treats anything you don't name as ambient context for the named contribution — no suppression required.

Bad:    "Image 2: Reference for outfit. Ignore the person, pose, face, and background."
Good:   "Image 2: Use only for the shirt — collar, button placket, chest pocket, fabric weave."

Bad:    "Image 5: Collar reference. The face visible at the top is NOT the character."
Good:   "Image 5: Use only for the collar construction — point shape, spread angle, stand height."

The rule: list what to use; never list what to disregard. If a reference contains a contaminant (a face, a hat, a backdrop) the user doesn't want in the output, the way to suppress it is to specify the positive replacement elsewhere ("the identity comes from Image 1") and let the named-use scoping carry the rest.

*Scope to all the positive attributes you want — narrow scoping strips co-baked ones.* Scoping a reference to a single attribute ("use only for the silhouette") can drop other attributes baked into that reference's framing: the camera angle, the orientation, the lighting direction it happened to be shot at. If you need those too, name them — "use Image 2 for the silhouette and the 3/4 front camera angle". Two positive contributions from one reference, both explicit. See capability-patterns.md "Reference Orientation Lock" for a worked instance.

Minimal Directive Pattern

The whole pattern:

[Reference block]

Replace [scope] with [pointer to reference].

One directive that points to the change. The verb's implicit scope carries the preservation work — Replace edits in place by definition, so everything else stays. No stop clause needed.

Example:

Image 1: Base photograph to edit
Image 2: Character and wardrobe reference

Replace the person in Image 1 with the woman from Image 2, wearing her exact outfit from Image 2.

The directive's job is to connect the dots between images — name what's being swapped, point to where the replacement comes from. Add clauses beyond this only when the model is observably dropping a specific element you need to keep; in that case name only that single element in positive form ("Keep the seamless gray backdrop intact"), then stop.

Why minimal beats verbose. Every adjective, color word, or preservation enumeration is a degree of freedom the model reconciles against the reference image pixels. Text-vs-image conflicts get resolved by blending both signals — the result matches neither. Over-specifying what the reference already shows actively degrades fidelity. Add detail only when the model cannot infer it from the references and you have a specific outcome in mind for it.

No "do not change anything else" stop clause. Earlier versions of this skill used Do not change anything else. as the keystone of the minimal directive. Production evidence showed that clause activates the concept of changing other things — same negation-biases-toward-the-concept mechanism the Core Prompting Principle warns about. The verb's implicit scope is sufficient; the stop clause is gratuitous and counterproductive.

Verb choice.

• Replace anchors to the base scene (model edits in place). Use this for in-place edits.
• Change allows full recomposition — use only when you want the model to consider discarding the scene.

"Only" after the verb tightens scope: "replace only the front figure" beats "replace the front figure." Sentence order affects spatial placement — the element mentioned last in a spatial assignment tends to land in the more prominent position.

Per-Reference Role Assignment

For prompts with three or more references, a single positively-framed directive sentence outperforms a bulleted role list. The pattern: one sentence that assigns each reference its specific contribution, enumerating attributes positively, using replication verbs.

Canonical template:

Perfectly replicate the exact [element] from Image [N]; the exact [element]
from Image [M]; the [element] from Images [P and Q]; and the [environment,
lighting, and finish] from Image [S].

Worked example (scene composite):

Perfectly replicate the exact building facade and signage from Image 2; the
parked vintage car from Image 3; the storefront awning from Image 4; and the
dusk sky, street lighting, and color grade from Image 1.

What makes this work, structurally:

• Per-reference role assignment — every image gets a positively-named job, no ambiguity about which signal goes where
• Enumerated attributes per image — "facade + signage" not "the building"; name the specific parts, not the whole
• Replication verbs — "perfectly replicate", "exact" — positive intensifiers, zero negation
• Single coherent sentence — one directive carries the whole multi-ref assignment, easier for the model to parse than a bulleted block

When the prompt has 3+ references, default to this form. For a fashion worked example (face + garment construction + fabric + lighting across six references), see capability-patterns.md "Multi-Reference Fashion Directive".

Inventory Preamble (Nano Banana + thinking high)

For multi-reference composition with Nano Banana at --thinking high, prefix each reference's role with a "silently inventory" instruction. This forces Gemini's auto-regressive head to reason about each reference's design-critical details before diffusion activates — lifting adherence to the attributes you've assigned each reference measurably.

When to use:

• Multi-reference composition with 3+ references
• Nano Banana + --thinking high only (Pro has a fixed reasoning budget; no benefit)
• Skip for single-reference edits (overkill) and t2i (irrelevant)

Prompt template (paste verbatim into your prompt):

## Reference inventory — analyze silently before generation

Image 1 — [Role: the bundle-source for X, Y, Z]. Silently inventory:
[the specific attributes this reference owns — enumerated positively].

Image 2 — [Role: the source for attribute W]. Silently inventory:
- [the precise geometry/structure of W — enumerated per attribute]
- [any co-baked attribute you also want from this reference, e.g. orientation]

[continue per reference]

Follow the inventory block with a single positive directive sentence (Per-Reference Role Assignment, above) and any CRITICAL sections needed for geometry lock or continuity. For a worked fashion inventory (a reference scoped to both cuff construction and arm orientation), see capability-patterns.md "Reference Orientation Lock".

Constraint Locking with CRITICAL Sections

A ## CRITICAL — [attribute] block is a general constraint-locking primitive, not a fixed menu. Any attribute the model tends to drift on can get its own CRITICAL section that names the target positively and in detail. Geometry and continuity (below) are the two with full worked treatment, but production prompts routinely stack several different locks in one prompt:

It's a balance. Each CRITICAL section removes a degree of freedom — raising fidelity on that attribute, but also adding tokens the model must reconcile and risking crowding out others. Lock the attributes that both (a) matter for this shot and (b) the model is actually drifting on. A simple t2i or single-element edit needs none. A complex multi-reference composition — where identity, construction, lighting, and skin realism all have to hold at once — earns several stacked locks. The count scales with how many independent things can drift, not with how ambitious the prompt is. Add a lock when you observe drift; don't pre-emptively lock everything. An attribute the references already carry reliably (because a hero image encodes it) needs no lock — see Single-Reference Collapse.

Two empirical patterns from production:

• Skin & finish is the near-universal lock for photorealistic human shots. Generative skin reliably drifts toward plastic, waxy, or over-retouched, so it earns a lock even when every other attribute is stable. It is often the only lock a hero-anchored shot needs.
• The harder it is for the references to carry an attribute, the more it needs an explicit lock. A back view where the face is mostly hidden has almost no pixels to anchor identity, so identity must be re-asserted in text even though a hero portrait exists. When a reference can't be used for a lock (e.g. a construction reference that leaks an unwanted face), describe the attribute in text instead and annotate the header — ## CRITICAL — Collar geometry (described, not image-referenced).

Place CRITICAL sections after the generation directive and shot description, one per attribute, each headed ## CRITICAL — [attribute]. Phrase every lock positively (the rule from the Core Prompting Principle in SKILL.md).

Continuity Assertion (Composition Lock)

When an output should inherit a bundle of qualities from one reference — an identity, OR a product, OR an environment plus its light, grade, and finish — assert sameness in a single clause instead of enumerating each quality. The bundle-source can be any reference; name the attributes that reference owns.

This is a [shot] from the same [session / set / scene] as Image [N]:
same [subject], same [setting], same [light].

The phrase does enormous load-bearing work — production runs replaced multi-paragraph preservation blocks with this single sentence and got tighter coherence. Use it as a dedicated ## CRITICAL — Continuity section in any follow-up shot that should read as part of the same set as an earlier image.

Generic example — compositing a product onto a recurring set:

## CRITICAL — Continuity

This is a detail shot from the same set as Image 1: same product, same marble
table, same softbox lighting, same color grade. The bottle is the visual hero,
centered in the frame against the table surface.

This works because asserting continuity ("same set as Image 1") re-anchors the whole bundle in one token-cheap clause, where re-describing each quality separately would multiply the degrees of freedom the model has to reconcile against the reference. For a fashion worked example (back-of-wrist detail anchored to a hero shoot), see capability-patterns.md "Detail Shots".

Single-Reference Collapse

Once one image reliably encodes a locked bundle of attributes — because an earlier generation produced it, or because it was assembled for the purpose — drop the references that originally contributed those attributes. A composite built from six references to establish a subject can collapse to two inputs for follow-ups: the locked image as the bundle-source, plus the single reference for the new attribute being introduced.

Fewer references means fewer competing signals, which raises fidelity on the attributes that matter. The collapse is not domain-specific:

• Character work — once a hero portrait locks the face, drop the turnaround/character sheets; use the portrait plus the new pose or wardrobe reference.
• Product work — once a hero render locks materials and lighting, drop the CAD/lighting refs; use the render plus the new angle reference.
• Scene work — once an establishing frame locks the environment and grade, drop the mood-board refs; use the frame plus the new foreground element.

Which reference becomes the bundle-source is a per-task choice, not a fixed rule. For the fashion instance (a hero front shot collapses the character sheet and lighting reference for every follow-up detail crop), see capability-patterns.md "Detail Shots".

Geometry Enumeration

A generic "match Image 2 exactly" does not preserve specific geometric attributes — the model reads "exactly" aspirationally and lets dimensions, edge shapes, counts, and angles drift seed-to-seed. To lock geometry, enumerate each attribute explicitly and positively in a dedicated ## CRITICAL — Geometry match section.

This applies to any object with specific geometry the reference cannot be trusted to carry on its own:

• A logo — stroke weight, corner radius, letter-spacing, x-height, overall aspect ratio
• An architectural feature — window proportions, column count, roof pitch, bay spacing
• A product silhouette — neck-to-body ratio, shoulder curve, base diameter
• A face — feature spacing, jaw angle, brow position

Phrase every attribute positively — "sharp 90° corners" not "not rounded", "a single fastener at the edge" not "no double row". For the fashion garment-region instance (cuff / collar / placket / sleeve attribute table), see capability-patterns.md "Geometry Lock for Detail Shots".

Image Ordering & Numbering

Base image (the canvas being edited) goes first in the --input list — it becomes Image 1 in the prompt, the most natural labeling. Reference images follow in order:

--input base.jpg     -> Image 1 in prompt
--input ref_a.jpg    -> Image 2 in prompt
--input ref_b.jpg    -> Image 3 in prompt

Aspect-ratio auto-detection reads from the first input (the base), so the output matches your canvas without needing --aspect. Label your reference block to match input order exactly — mismatched labels cause role confusion and character drift even when the directive is otherwise correct.

---

Multi-Image Composition

Reference images provide visual context — the prompt connects them. Point to images by number, assign elements to positions, and describe only what the model cannot infer from the images themselves. Nano Banana supports up to 14 reference images; Nano Banana Pro supports up to 11 (6 objects + 5 character references).

---

Character Consistency

• Use follow-up edits for multiple views of the same character
• Reference distinctive features explicitly in follow-ups
• Include "exact same character" or "maintain all design details"
• Save successful designs as reference for future prompts

---

Semantic Masking

No manual masking needed. Language creates the edit boundary — name the element to define the mask, specify the replacement, constrain the scope:

"Using the provided image of a living room, change only the blue sofa
to a vintage brown leather chesterfield."

"Only" after the verb defines scope. The element name ("the blue sofa") defines the mask region. The change verb's implicit scope protects everything else — no stop clause needed.

---

Editing Failure Modes

Common ways i2i edits fail and how to avoid them. These patterns emerged from real production campaigns and apply to any editing workflow.

Color Labels Override Visual References

Every color word in an editing prompt creates a competing signal against the reference image. If you name a color ("rust", "terracotta", "olive green"), the model generates the text-defined tone rather than the actual shade visible in the reference. This happens because the model resolves text-vs-image conflicts by blending both signals — the result matches neither.

Remove all color words from editing directives. The reference block labels the image's role ("Reference shirt — women's linen blouse"); the directive says what to change ("Replace only the shirt with the blouse from the reference"). The reference image itself is the color spec.

This applies to any visual attribute already present in the reference: color, cut, texture, proportion. Naming these in text creates drift. If you want something replicated exactly, don't describe it — let the image be the sole authority.

High-Contrast Swap Targets

When replacing an element with something of a similar color (olive shirt → olive shirt of different cut), the model can't distinguish source from target and produces near-identical output. The fix is to choose a base image where the element being replaced is a contrasting color — e.g., use a white shirt base for an olive shirt swap. The high contrast gives the model an unambiguous replacement target.

Gemini Cannot Re-Frame

Gemini cannot execute virtual camera moves. Prompts like "zoom in on the storefront," "show this from a closer angle," or "crop to a tighter shot" will either reproduce the original composition or generate an inconsistent scene — they will not produce a re-framed version of the same content.

Always edit on a base image that already has the target angle, framing, and composition. If you need a closer shot, find or extract a frame at that angle rather than trying to prompt a re-frame.

Multi-Pass Editing

The minimal directive pattern (one Replace, no stop clause — see "Minimal Directive Pattern" above) works for a single change. When a prompt has two competing changes — garment swap plus sign text, outfit plus accessories, subject plus background — the model compromises on one.

Split into sequential passes: one change per generation call. Pattern for element replacement with correct proportions:

1. Pass 1: Remove the element entirely (e.g., "Remove the price sign and easel from the scene") 2. Pass 2: Re-add it using a visual reference (e.g., "Add the exact price sign and easel from image 2 to the right side of the shelf")

This remove-then-re-add approach is specifically important for text and sign elements, where text-only swaps change the words but distort the element's proportions and positioning.

Base Scene Contamination

Accessories and distinctive elements in the base image bleed into garment-swap outputs. If the base scene has a beret, the generated outfit may include a beret. If the base scene has sunglasses, they appear on the output model. Similarly, outfit references shot on plain studio backgrounds can override the base scene's location background — the gray studio backdrop replaces the street.

When choosing a base image for garment editing:

• Prefer images with minimal distinctive accessories
• Avoid bases where the model wears items (bags, hats, jewelry) you don't want in the output
• If using outfit references from studio shoots, verify the output preserves the base scene's environment

Pose to Make Unwanted Elements Impossible

When framing or composition language alone fails to suppress an unwanted element (positive crop instructions get interpreted aspirationally — "tight crop to forearm" still includes the belt), pose the subject so the unwanted element is physically not in the shot. The model gets a concrete physical solution instead of a suppression task.

Worked example: a cuff macro that kept including the trouser. The fix was not "no trouser in frame" — it was repositioning the arm:

Bad:   "Crop tightly to the forearm and cuff only. No belt, no trouser visible."
Good:  "The arm is held slightly away from the body so the cuff is silhouetted
        against the studio backdrop. The forearm and hand fill the frame against
        the seamless backdrop behind them."

The trouser is suppressed not by naming its absence but by giving the arm a physical position where the trouser cannot be visible. Same technique works for accessories ("the hands hang at the sides, fingers loose" makes hand-in-pocket impossible), facial features ("the head is turned profile to camera" makes both eyes impossible to show), and backdrops.

Asymmetric Directive Collapse

Gemini's editorial training prior couples contrapposto with symmetric framing — "one hand in pocket, the other at side" gets symmetrized to "both hands in pockets" on ~50% of seeds. Standard hedging language ("naturally asymmetric") doesn't help; the model defaults to its prior.

To improve compliance, name the asymmetry as the explicit goal and describe both sides positively in separate clauses:

Bad:   "Hands settle naturally — one in pocket, one at the side."
Good:  "Only the left hand is in the pocket. The right hand rests visibly at the
        right thigh with fingers loose. The arms are deliberately asymmetric."

Naming both sides removes the option of guessing; describing the asymmetry as the goal removes the option of regression toward symmetry.

Listed Alternatives Collapse

When a prompt offers the model multiple options for the same attribute ("hands at sides, OR hand in pocket, OR adjusting cuff"), Gemini picks one option and repeats it across every seed in the batch — defeating the purpose of offering alternatives for variety.

For pose or styling variety across a batch, run separate generations each with a single distinct directive. One prompt = one option; the batch flag controls per-prompt variance, not directive variance.

Per-Seed Variance

Image generation is stochastic — the same prompt with the same references produces meaningfully different outputs across seeds. For directives requiring precise execution (specific pose, asymmetric framing, exact crop, geometry lock), expect ~50% per-seed hit rate even with locked recipes. The remedy is --batch 3 or --batch 4 plus cherry-picking the obeying frame, not iterating prompt language to push consistency past ~75%.

When cherry-picking, judge against the primary transferred attribute first — whatever the shot exists to deliver — then secondary consistency (identity, environment), then staging (composition, framing). Decide what is primary per task before you generate; for a multi-reference detail shot the primary attribute is usually the construction being highlighted, not the identity carrying it.

Style Reference Lexicon

On-demand reference for aesthetic naming. Use these names in prompts to invoke specific visual characteristics.

---

Film Stocks

Modifiers: "pushed to 1600" (more grain, contrast), "cross-processed" (color shifts)

---

Camera Systems

---

Lenses

---

Animation & Studios

---

Illustration & Comics

---

Game Art

---

Graphic Design & Eras

---

Fine Art Movements

---

Photographers & Directors

---

Quick Combinations

These patterns work well together:

Portraits: "shot on Kodak Portra 400, Hasselblad medium format, soft window light"
Street: "Leica M10, 35mm Summicron, Cinestill 800T at night"
Product: "Phase One IQ4, studio softbox lighting, commercial quality"
Fantasy: "Studio Ghibli style, Makoto Shinkai lighting"
Horror: "Junji Ito aesthetic, high contrast black and white ink"
Retro: "Y2K aesthetic, chrome text, gradient background"

The lexicon is vast—these are samples. If you know a specific name, try it directly.