image-generation

name	image-generation
description	Image generation. Produces a still image from text, edits an existing image, or composites multiple images. Use for any output that is a single still frame — concept art, character references, product shots, scene keyframes, style explorations, background plates, virtual try-on, or image editing.
metadata	{"type":"primitive"}

When to use

Use t2i when the user wants a still image: concept art, product shots, character references, background plates, style samples, or any image that does not require motion.

---

Unified Prompt Structure

Every image generation prompt — whether creating from scratch, editing an existing image, or compositing multiple images — must follow a single unified structure. It consists of a general description of the image followed by a structured description of specific features.

[GENERAL DESCRIPTION]
<A 1-2 sentence overview of the image, setting the core subject, action, and composition.>

[STRUCTURED FEATURES]
SUBJECT: <Specific details of the focus/subject. Include reference links like @Image1 if modifying or preserving traits.>
ENVIRONMENT: <The physical place, background elements, and light sources (type, direction, quality).>
STYLE & MEDIUM: <Output medium type, camera lens/depth, color palette, and textures.>
CHANGES (if editing/compositing): <EDIT instructions, LOCK directives, and PHYSICS constraints to match existing elements.>
FORBIDDEN: <At least three specific entries for elements/artifacts to exclude.>

---

Prompt structure details

[GENERAL DESCRIPTION]

Provide a 1-2 sentence overview of the entire scene to give the model overall context.

• Good: "A close-up photographic portrait of a chef slicing red peppers in a sunlit restaurant kitchen."
• Bad: "A chef in a kitchen."

[STRUCTURED FEATURES]

SUBJECT

Describe the single subject or focus that the eye lands on first.

• Details: Material, physical anchors (e.g., jawline, eye color, fabric type, exact color names like "faded slate denim"), and condition (new, worn).
• Reference Anchoring: If inheriting traits from a canvas reference (e.g., @Image1), specify: "Same person as @Image1. Maintain [list 3-4 specific traits]. Do not alter facial proportions, eye shape, or hairstyle."
• Emotion: Do not describe emotion directly (e.g., "sad"). Describe the physical facial features that produce it (e.g., "furrowed brow, downcast eyes").

ENVIRONMENT

Describe the physical setting and lighting.

• Setting: Be concrete. Specify architectural details, era, season, time of day, and weather (e.g., "east-facing corner of a 1970s laundromat, 6pm, winter").
• Lighting: Name every light source by type, direction, and quality. Never use subjective mood words (e.g., "cinematic," "golden hour," "beautiful").
  • Good: "Warm tungsten side-light from camera left," "neon blue rim light at 2 o'clock," "single overhead bulb casting a pale yellow glow."
• Composite Setting: If inheriting environment from a canvas reference (e.g., @Image3), specify: "Adopt environment, lighting, and layout from @Image3."

STYLE & MEDIUM

Name the output medium type and style properties explicitly.

• Medium: Editorial photo, digital painting, storyboard frame, product mockup, etc.
• Camera Details: Lens choice, aperture (e.g., "Sony A7R IV, 85mm prime, f/1.8 shallow depth of field"), and film stock (e.g., "Kodak Portra 400 fine grain").
• Deconstruct Style: If matching style from a reference (e.g., @Image2), deconstruct it into three channels:
  1. Palette: Named colors and shadow treatment (e.g., "Adopt color palette from @Image2: shadows deep navy, never pure black").
  2. Edge treatment: Line weights, silhouette hardness (e.g., "hard ink outlines," "soft photographic edges").
  3. Silhouette language: conventions of pose, proportions.

CHANGES (if editing/compositing)

Used only when modifying or merging existing image(s).

• EDIT: Exactly what changes in one unambiguous sentence. One change per prompt.
• LOCK: What must stay identical (e.g., face, pose, outfit, layout, background).
• PHYSICS: Match physical properties of the existing scene: shadow direction, contact shadows, grain, color balance, scale relationships.

FORBIDDEN

Never skip this section. Provide at least three entries to prevent hallucination and distortion.

• Exclusions: "No secondary subjects. No duplicate objects. No over-sharpening."
• AI Tells: "No symmetry artifacts. No plastic-looking skin. No watermark-shaped artifacts."
• Realism Layer: "2-3% film grain overlay. Slight facial asymmetry. Visible pore texture."

---

Illustration Style Vocabulary

See references/illustration-styles.md — loaded automatically alongside this file. Use it to populate the STYLE & MEDIUM section and to surface style options via ask_user when the user has not specified a visual style.

---

Special Case: Character Identity Boards

See references/character-identity-board.md — loaded automatically alongside this file.

---

Special Case: Storyboard Sheets

See references/storyboard.md — loaded automatically alongside this file.

---

Model hints

• gemini-3.1-flash-lite-image: fastest, lowest latency, best for quick drafts and iterations.
• gemini-3.1-flash-image: default — fast, high quality, best for general use.
• gemini-3-pro-image: highest quality; use for hero shots or final keyframes only when the user requests it.
• Always use the canvas default model unless the user explicitly requests otherwise.

---

Common failures

• Vague subjects ("a nice scene") produce generic output — anchor to specific physical facts.
• Mood words ("cinematic," "stunning," "epic," "atmospheric") override the model's knowledge with noise — cut them.
• Conflicting medium cues ("photorealistic watercolor") confuse the model — pick one.
• Skipping FORBIDDEN lets the model hallucinate secondary subjects, extra limbs, and style drift.
• Aspect ratio shapes composition: portrait subjects → 9:16, landscapes → 16:9, product shots → 1:1.