Image Generation Guide

Core Rules

Reference Loading Contract

References are part of the required workflow, not optional background reading.

Before constructing a prompt, choosing a final task_type, or calling any image tool:

1. Match the request to the Scene Router.
2. Load every matched scene reference listed in the router table.
3. For composite workflows, load only the composite reference plus the references for the selected output scenes.
4. Apply the loaded reference's prompt template, hard constraints, safety boundaries, and tool invocation rules.
5. If a request matches multiple scenes for the same output image, read each matched reference, then decide whether to merge them into one call using Step 4.

Do not skip a reference because the router table appears sufficient. The table is only an index; the detailed rules live in references/.

Reference loading index:

Request Processing Pipeline

Process every request through these steps in order:

Step 0 — Image Intake

If the user provides one or more images, inspect the image before routing.

Identify:

• Main subject
• Elements that must be preserved
• Visible text, logos, labels, watermarks
• Current aspect ratio
• Quality issues such as blur, low resolution, artifacts, occlusion
• Whether the image appears to be a product photo, poster, document, logo, model photo, or scene photo

Use this intake result to build preservation clauses and choose routing. Never infer hidden or occluded product details.

Step 0.5 — Image Edit Source Preflight

Before any image_edit call, prepare every reference image:

1. Read before edit: inspect the image source and confirm it is reachable, decodable, and image-like. Capture at least format/MIME, dimensions, file size when available, visible content summary, and any quality risks that affect routing.
2. Local path handling: if the user provided a local filesystem path, do not pass it directly to image_edit. Read and validate the local file first, upload it to the configured CDN or asset host, then use the returned HTTPS URL as the reference_images input.
3. Remote URL handling: if the user provided an HTTP(S) URL, verify that it can be read as an image before editing.
4. Fail closed: if the image cannot be read, decoded, verified, or converted to an HTTPS URL, stop before image_edit and report the blocker. Do not guess-edit an unread image or pass file:// / raw local paths to remote image-edit tools.

When uploading local images, avoid exposing sensitive metadata: strip EXIF/GPS data unless the user explicitly needs it preserved, and do not log signed CDN URLs or private local paths.

Step 1 — Outcome Intent First

Before choosing any task_type, identify the user's desired final outcome.

Classify the request by outcome intent first:

task_type is only an execution hint. It must not replace outcome-intent analysis.

Step 2 — Non-AI Task Interception

Before invoking any AI image tool, check whether the request is a non-AI operation. If the user's core intent is to change the image's size, file weight, format, or orientation without altering content, route to native (non-AI) tools instead.

Key indicator: phrases like "keep everything else unchanged", "just resize", explicit pixel dimensions with no content change, or file-size constraints ("under 2MB") strongly signal non-AI tasks.

SKU-related requests such as "split into SKU images" or "make each SKU into a listing image" must go through Step 2.5 before deciding native vs AI.

Mixed requests:

• Content-changing AI operations usually run first.
• Final delivery operations such as resize, crop, compress, and format conversion usually run last.
• Only run crop/resize first when the user explicitly requires a fixed canvas before editing.

If the Agent toolset lacks a dedicated resize/compress tool, inform the user that this operation is not supported by the AI image tools and suggest alternatives.

Step 2.5 — SKU Asset Workflow

SKU requests are not always native-only. First classify the user's SKU intent before selecting tools.

Rules:

• Never invent SKU count, colors, materials, or variants unless the user explicitly requested them.
• For batch SKU work, first identify the expected output count. If the count is unclear or visual separation is ambiguous, ask for confirmation.
• For listing-ready SKU images, output one image per SKU. Do not satisfy a multi-SKU request with one combined image.
• Preserve each SKU's exact color, pattern, shape, material, labels, accessories, and visible details.
• Use AI only for listing standardization or requested variant generation; use native tools for pure extraction/crop/format delivery.

Step 3 — Ambiguity Check

Evaluate whether the request contains enough information to proceed:

Safe visual defaults include cleaner background, balanced composition, soft natural lighting, sharper product presentation, corrected product centering, and preservation of product identity.

Do not add new claims, text, logos, certifications, dimensions, materials, or product features unless the user provides them.

Ask the user with specific, selectable options when the host provides a prompt UI; otherwise ask a concise plain-language question (e.g., "What would you like to do: change background, remove watermark, adjust colors, add text, or something else?").

Step 4 — Multi-Intent Execution Planner

If the request contains 2 or more intents (including mixed AI + non-AI), plan by output image and minimize AI calls. Decomposition is for reasoning; it does not automatically mean sequential execution.

1. Identify all requested intents and the expected output count.
2. Separate native delivery intents: resize, crop, compress, rotate, and format conversion should usually run last with native tools and should not trigger an AI call.
3. Group AI intents by output image: if several visual changes belong to the same final image, merge them into one prompt when the tool can satisfy them together.
4. Load references for every matched scene using the Reference Loading Contract.
5. Choose execution mode:
   • single_purpose: only when the request exactly matches one dedicated task and no other visual/layout/platform changes are needed.
   • merged_simple: one simple_generation call for compatible product-fidelity edits such as scene/background, white/light hero styling, centering, shadow, lighting cleanup, local cleanup, logo placement, or product color change.
   • merged_complex: one complex_generation call for dense layouts, selling-point images, comparison grids, tech packs, or multi-region visual design in a single output.
   • true_sequential: only when a previous output is required before the next step, when tool limitations force it, or when the user explicitly requests separate intermediate outputs.
6. Execute the minimum number of AI calls needed for the requested output count, then apply native delivery operations last.
7. Aggregate results and state any skipped or native-only operations.

Cost guard:

• Prefer one AI call per requested output image.
• Do not multiply calls by the number of detected intents when the intents can be expressed in one prompt.
• If a plan would require more AI calls than the requested output count, compress the plan first; ask or explain only when compression would reduce quality or violate safety/tool constraints.
• Platform image sets and SKU batches may require multiple calls because the user expects multiple output images, but each output should still use the fewest feasible calls.

Merge examples:

Use true_sequential for cases such as isolating each SKU before standardization, removing a dense watermark before a high-fidelity edit, or generating separate tech-pack drawings requested as distinct outputs.

Step 5 — Scene Routing

Match the request against the Scene Router below (Priority 1 → 4). Use the first matching priority level.

Scene Router

Priority 1 — Platform Product Image (Composite)

Platform Product Image is a composite workflow — it consults platform requirements first, then delegates to White Background, Scene Image, Model Showcase, etc. as sub-tasks.

Sub-task execution rules:

• When the user uploaded product images, ALL sub-tasks MUST use image_edit. Never use image_generate when reference images exist.
• Only Selling Point Image and Logo Design sub-tasks may trigger user clarification (for selling-point confirmation or brand context). All other sub-tasks execute directly unless safety or missing required inputs block execution.

Platform image set planner: When the user requests multiple listing images (e.g. "3/5/6/11 main images", "main images + detail page images", "Alibaba.com product image set"), create an execution plan before generation:

1. Hero/main image — full product, clean white or light background, no promotional text unless the platform allows it
2. Scene image — B2B or use-context background while preserving the product
3. Detail image — visible material/structure close-up only
4. Selling-point image — only user-provided or visible/verifiable claims
5. Scale/usage image — only if supported by the image or user request
6. Packaging/accessory image — only if visible or user-provided

Rules:

• Generate or edit one final image per planned output. Do not split a single planned output into multiple AI calls unless Step 4 requires true_sequential.
• If the tool can only produce one image per call, explicitly run multiple calls or state the limitation.
• Output count must match the requested count when feasible; otherwise explain which planned images were produced and which remain.
• For uploaded product images, every planned image must preserve product identity and use image_edit.

Priority 2 — Single-Purpose Scenes

These use dedicated task_type values that perform only one function. They are valid only for exact single-operation requests:

Single-Purpose Use Rule: Use these task_types only when the user's request exactly matches the single operation and does not require layout, composition, lighting, platform compliance, text editing, ratio change, or multiple visual changes.

Watermark removal is only allowed when the user owns the image or has rights to edit it. Do not help remove third-party copyright marks, platform watermarks, photographer signatures, or ownership identifiers to bypass licensing. Allowed cases include removing the user's own watermark, accidental overlays, stains, dust, scanner marks, or non-ownership visual clutter.

Do not treat every "delete text/logo" request as Watermark Removal. If the target is product/package text, a product brand mark, or user-specified local text, route to Text Editing's local text removal flow. If the target looks like an ownership or licensing mark and rights are unclear, ask for confirmation before editing.

Single-Purpose Fallback: Switch to a merged simple_generation, merged complex_generation, or true_sequential plan when:

• The request contains 2 or more intents
• The user asks for platform-ready or listing-ready output
• The user uses broad outcome language such as "professional", "optimized", "cleaner", "main image", or "selling image"
• The user specifies a non-1:1 aspect ratio
• The user requests follow-up edits after the initial single-purpose operation

Priority 3 — Specialized Editing Scenes

Image Translation mandatory rule: When the user requests an edited translated image, load references/image-translation.md and call image_edit after required inputs are available. Do not substitute a text-only translation for an image-edit request.

Priority 4 — General (Fallback)

If no specialized scene matches, use semantic instructions with simple_generation or complex_generation based on complexity. Refer to references/style-guide.md for prompt enrichment vocabulary (atmosphere, composition, lighting, materials).

Key Disambiguation Rules

These cover the most commonly confused routing decisions:

Strict Product Fidelity Mode

Enable this mode whenever the user asks to keep the product unchanged, produce platform/listing images from a reference, remove/replace text while preserving the product, make a white-background hero, or change only the surrounding scene/background.

Append this constraint to all relevant image_edit prompts:

Keep the product exactly unchanged — preserve geometry, color, texture, labels, and camera angle.
Only change: [describe allowed changes here].
Do not redraw, simplify, or invent any product detail.

Keep the constraint concise (≤3 lines). Verbose constraint lists (enumerating 20+ protected items) do not improve model compliance and can reduce prompt execution quality.

When product fidelity conflicts with a more creative instruction, product fidelity wins unless the user explicitly asks to redesign the product.

Task type rule: When Strict Product Fidelity Mode is active, prefer simple_generation over complex_generation unless the loaded reference requires dense layout or annotations. In many runtimes, complex edit modes are more likely to affect the whole image, increasing product drift risk.

Selling Point Image priority rule: When a request combines marketing expressions (selling point, copy, layout, callout, comparison) with other scene keywords (detail, scene, model), route to Selling Point Image. Only Selling Point Image can output copy + layout + visual anchors together.

Resolution Routing

When the user specifies an output resolution:

Task Type Safety Rules

task_type is an execution hint, not the user's intent.

Before selecting a task_type:

1. Identify the user's desired final outcome.
2. List all required visual changes.
3. Check whether a single-purpose task_type can satisfy all required changes.
4. If not, use a merged simple_generation, merged complex_generation, or true_sequential plan only when required by Step 4.

Use single-purpose task_types only when the user requests exactly one operation:

• white_background: only pure white background replacement
• hd_upscale: only clarity/resolution improvement
• watermark_removal: authorized removal of watermarks, URLs, contact info, QR codes, accidental overlays, stains, dust, scanner marks, or non-product visual clutter. Product/package text and product brand marks are not this route.

Do not use single-purpose task_types for:

• Platform-ready product images
• General image optimization
• "Make it professional"
• Mixed requests
• Follow-up refinements
• Layout, text, selling-point, or composition changes
• Requests involving product coverage, shadows, centering, lighting, or platform compliance

Task Type Misrouting Guard

Simple vs Complex task_type

When in doubt, use simple_generation. The downside of simple_generation on a complex task is lower layout quality; the downside of complex_generation on a fidelity task is product destruction.

complex_generation Risk Guard

complex_generation is higher-risk for product-fidelity tasks because many image-edit runtimes treat complex edits as broader redraws rather than localized edits. Use it only when the requested output genuinely needs dense layout, annotations, comparison grids, or full-image design composition.

Default to simple_generation unless the task genuinely requires complex layout:

Rule of thumb: If the product must stay unchanged, use simple_generation. The "complex" in the user's request description does not mean you should use complex_generation — a visually rich background or detailed scene is still a simple_generation task when the product is preserved.

If using complex_generation with a product reference, always enable Strict Product Fidelity Mode.

Prompt Construction

Generation Prompt Formula

[Shot type] of [Subject] in [Setting], [Action/State].
[Style], [Composition], [Lighting], [Color palette], [Quality].

For text in images, use explicit quotes: Display "LIMITED EDITION" in bold serif font.

Editing Prompt Formula

[Edit instruction targeting specific area].
[Preservation clause (concise, ≤3 lines)].

Preservation clause template (append to every edit prompt):

Keep the product exactly unchanged — preserve geometry, color, texture, labels, and camera angle.
Only change: [specific allowed changes].
Do not redraw, simplify, or invent any product detail.

Keep it concise. Long enumeration lists (20+ protected items) do not improve compliance and may reduce model execution quality. The model responds better to clear, short constraints than to exhaustive lists.

Example — Scene change:

Place the product on a modern kitchen countertop with warm morning light.
Keep the product exactly unchanged — preserve geometry, color, texture, labels, and camera angle.
Only change: background/scene.
Do not redraw, simplify, or invent any product detail.

Result Check

After receiving a generation or editing result:

1. Preservation audit: Compare the result against the preservation clause. If the model altered protected elements (product shape distorted, text removed, colors shifted), retry with a stronger constraint — e.g., add "CRITICAL:" prefix, list each protected element individually, or reduce edit scope.
2. Intent completeness: Verify all user-requested changes are present. If a sub-task from Step 4 was missed, execute the remaining sub-tasks on the current output.
3. Quality gate: If the result is clearly unusable (heavy artifacts, wrong subject, garbled text), inform the user and offer to retry with adjusted parameters (e.g., switch simple_generation → complex_generation, or simplify the prompt).

Hard failure conditions:

• Product shape, structure, SKU color/pattern, packaging text, logo, handle, seam, hole, accessory, or camera angle changed when not requested
• A crop/split/resize/format task was handled by generating a new product image
• Multi-image or multi-SKU output count does not match the requested/confirmed count
• White-background output changes the product or leaves damaged/blurred edges
• Text editing/removal causes garbled text, misspellings, or modifies unspecified text
• Platform hero image includes prohibited overlays, watermarks, contact information, or unsupported claims
• User requested "do not change the product" but the result redraws or reimagines the product

Scene Acceptance Criteria

Do NOT silently retry indefinitely. After 2 failed attempts at the same task, inform the user of the limitation and suggest alternatives.

Tool Contract / Host Mapping

Concrete tool names may vary by runtime. Map workflow intent to available tools.

Required conceptual operations:

• Text-to-image generation
• Image-to-image editing
• Native resize/crop/compress/format conversion, if available
• User clarification / selection prompt, if available

For image generation:

• Required: prompt
• Optional: aspect_ratio, resolution, task_type

For image editing:

• Required: reference_images, prompt or task_type
• Optional: aspect_ratio, resolution

If the runtime lacks a native resize/compress/format tool, use available local image-processing libraries when permitted. If unavailable, explain the limitation to the user.

Tool Reference

Canonical task_type values

For image_generate:

• simple
• complex

For image_edit:

• white_background
• hd_upscale
• watermark_removal
• simple_generation
• complex_generation

image_generate

For generating images from scratch (no reference image).

image_edit

For editing an existing image.

Aspect Ratio

Supported Values

1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 9:16 | 16:9 | 21:9

Selection Rules

1. User specified a supported ratio → use it directly
2. User specified an unsupported ratio (e.g., 5:3) → inform user and ask to choose from supported list
3. Single-purpose scenes (white_background, hd_upscale, watermark_removal) only support 1:1. If the user needs a different ratio, auto-switch to simple_generation
4. User did not specify →
   • Single-purpose scenes → default 1:1
   • Other scenes with uploaded image → match closest ratio from the table below
   • Other scenes without image → default 1:1

Auto-Match Table (for uploaded images without user-specified ratio)

Compute W/H ratio of the uploaded image and find the matching range. If the closest ratio deviates >10% from the original, briefly inform the user about potential cropping.

Multilingual Handling

When the user's input is not in English:

1. Detect the input language
2. Preserve key terms: Embed the user's original nouns/descriptions directly into the prompt rather than translating them (translation can distort meaning)
3. Build prompts in English: The image model works best with English prompts, but anchor key concepts from the original language
4. Respond in the user's language

Example: User writes "A máquina parada (dor financeira)" (Portuguese) → Extract: "máquina parada" = stopped machine, "dor financeira" = financial pain → Prompt uses: "idle/stopped CNC machine, conveying financial loss and downtime frustration" → NOT: "professional, precise, clean machine" (semantic reversal)

Batch Operations

When the user references a folder or multiple images:

1. List the images in the folder/selection
2. If the user has not specified what to do per image, ask for the operation before editing
3. If all images need the same operation → batch-execute the same scene
4. If different images need different operations → classify and route individually
5. Never guess-edit folder contents without explicit instructions