generate_image
Generate or edit images from natural language instructions, using Amazon listing compliance rules and character-consistent references to produce on-brand product visuals.
Instructions
Catalog entry. Runs in your Kuudo deployment, not here. Generate or edit images with Google Gemini (Nano Banana) from natural language instructions. For OpenAI gpt-image-2, use the sibling generate_openai_image tool. For Amazon / Seller Central listing images, FIRST read the skill://amazon-product-image/SKILL.md resource (via read_resource) for the marketplace image-compliance rules, then generate/audit against them. ## CHARACTER CONSISTENCY Use public image handles for character-consistent image generation: generate_image( input_images=["agent-iris://images/img_12"], mode="generate", prompt="PRESERVE EXACTLY: character's facial features. NEW: Professional headshot...", model="gemini-3-pro-image" ) Explicit generate mode uses the image handle as conditioning rather than an edit source. ## EDITING AN EXISTING IMAGE For local bytes, upload with POST /images first, then pass the returned handle. For a public hosted image, pass the HTTPS URL directly: generate_image( input_images=["https://example.com/source.jpg"], mode="edit", prompt="Change the background to a beach sunset" ) ## ITERATING ON A RESULT (high-fidelity chained edit) — PREFERRED Every generate/edit response returns an interaction_id. Pass it back to refine the SAME image while preserving the rest of the composition — no need to re-send the source. This beats re-editing from bytes for edit fidelity: generate_image( interaction_id="v1_Chd...", # from the previous response prompt="Recolor the mug to beige. Change nothing else." ) TTL: ~55 days (paid) / 1 day (free). ## COMPOSITING (Person from image A into scene B) Use multiple references with generate mode: generate_image( input_images=["agent-iris://images/img_12", "gemini://files/beachRef"], mode="generate", prompt="Place character from image 1 into the beach scene from image 2..." ) ## OPERATION PRESETS Use operation="icon", "pattern", "diagram", "storyboard", or "photo_repair" for strict defaults around model, aspect ratio, and prompt framing. ## Mode Auto-Detection: - interaction_id → EDIT mode - operation="photo_repair" → EDIT mode - operation="icon"/"pattern"/"diagram"/"storyboard" → GENERATE mode - operation="general" with one input image → EDIT mode - Multiple input images or pure prompt → GENERATE mode Returns both MCP image content blocks and structured JSON with metadata.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | Requested image count (model may return fewer). | |
| mode | No | Operation mode: 'auto' (default), 'generate', or 'edit'. AUTO BEHAVIOR: interaction_id or photo_repair → edit mode; generation presets → generate mode; one general input image → edit mode. USE 'generate' FOR: Creating new images with character reference, style transfer, conditioning. USE 'edit' FOR: Modifying a specific existing image (change background, outfit, add text). You can override auto-detection by explicitly setting mode='generate' or mode='edit'. | auto |
| model | No | Model selection. gemini-3.1-flash-image: Nano Banana 2 (DEFAULT), supports grounding, 14 aspect ratios, and 0.5K-4K output. gemini-3-pro-image: Nano Banana Pro, professional asset production, grounding, 14 total references, 1K-4K output. gemini-2.5-flash-image: Original Nano Banana — fast drafts ($0.039/image), no grounding support. Legacy -preview aliases are accepted and normalized to current model IDs. | |
| prompt | Yes | Clear, detailed image prompt. Include subject, composition, action, location, style, and any text to render. Add 'Square image' or '16:9' in the text to influence aspect ratio. | |
| operation | No | Strict operation preset: general, icon, pattern, diagram, storyboard, or photo_repair. | general |
| resolution | No | Optional resolution. gemini-3.1-flash-image supports 0.5K, 1K, 2K, and 4K. gemini-3-pro-image supports 1K, 2K, and 4K. gemini-2.5-flash-image supports 1K only. | |
| output_name | No | Optional base name for output file(s). If provided, files will be named '<output_name>.png' (or '<output_name>_1.png', '<output_name>_2.png' for multiple images). Use descriptive names like 'brand-linkedin-headshot' or 'product-hero-banner'. If not provided, defaults to timestamped names like 'gen_20251217_120000_1_1_abc123.png'. | |
| aspect_ratio | No | Optional output aspect ratio. Standard: 1:1 (square), 3:4, 4:3, 2:3, 3:2, 4:5, 5:4, 9:16 (portrait), 16:9 (landscape), 21:9 (ultra-wide). New in Nano Banana 2: 1:4 (tall strip), 4:1 (wide banner), 1:8 (ultra-tall), 8:1 (ultra-wide). | |
| input_images | No | Images for editing or conditioning. Accepts agent-iris://images/{image_id}, gemini://files/{name}, and http(s) image URLs. Hosted URLs are fetched server-side inside this authenticated tool call; upload local bytes with POST /images when a durable server handle is needed. | |
| use_grounding | No | Enable Google Search grounding for real-time data retrieval before generation. REQUIRED for infographics, charts, current events, statistics, or any real-world data. IMPORTANT: Grounding works with 'gemini-3.1-flash-image' (default) and 'gemini-3-pro-image'. Default: False. | |
| interaction_id | No | Interactions API id from a PRIOR generate/edit call (e.g., 'v1_Chd...'). PREFERRED way to iterate on an image: pass it to chain a high-fidelity edit that preserves the rest of the composition (no need to re-send the source image). Implies edit mode. TTL ~55 days (paid) / 1 day (free). | |
| thinking_level | No | Optional thinking level for Gemini 3 image models. Allowed values: low or high. Use high for complex compositions, text-heavy images, or unusual prompts. Leave unset for the model default. | |
| include_preview | No | Whether to ALSO embed the inline base64 thumbnail preview block(s). Default false (link-first): the response is the text summary + signed download URLs (including a signed thumbnail URL) + structured metadata, with no base64 — saving context tokens. Set true to additionally embed the inline thumbnail for a quick interactive visual check on a single image. Thumbnails are always stored server-side and reachable via the signed thumbnail URL regardless of this flag. | |
| negative_prompt | No | Things to avoid (style, objects, text). | |
| system_instruction | No | Optional system tone/style guidance. |