Image Generation Tools

Tools for creating and editing images via MCP.

Pro Prompting Tips

Golden Rules from Google DeepMind:

1. Edit, Don't Re-roll - If 80% correct, use continue_editing
2. Natural Language - Full sentences, not tag soups
3. Materiality - Describe textures: "brushed steel", "soft velvet"
4. Context - Add "for whom": "for a luxury cookbook"
5. Identity Locking - "Keep facial features exactly the same as Image 1"

Learn Pro Best Practices →

Advanced Techniques

Negative Prompting - Tell the model what NOT to include:

{
  "negative_prompt": "no date stamp, no text, not rustic"
}

Prompt Evolution - Start simple, iterate:

1. generate_image({ prompt: "A portrait" })
2. continue_editing({ prompt: "make it dramatic" })
3. continue_editing({ prompt: "add studio lighting" })

Multi-Purpose References - Use images for style, branding, colors:

"Logo from Image 1, styled like Image 2, colors from Image 3"

Upscaling - Small images (150x150+) to 4K:

{
  "prompt": "Upscale to 4K",
  "model_id": "gemini-pro-image",
  "resolution_tier": "4k"
}

generate_image

Generate new images from text prompts. Routes to whichever provider you select via model_id (Nano Banana 2 Lite by default; Nano Banana 2, Go Bananas! Pro, OpenAI GPT Image 2, or GPT Image 2.5 Flare/Sunburst if your tenant has them in allowedModels).

Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Text description (Gemini max 16384 chars, OpenAI models max 32000 chars)
negative_prompt	string	No	What to avoid (max 1024 chars)
aspect_ratio	string	No	Image dimensions (default: square)
n	number	No	Number of images 1-4 (default: 1)
model_id	string	No	Model selection — gemini-flash-lite-image (default), gemini-flash-image, gemini-pro-image, openai-gpt-image-2, openai-gpt-image-2.5-flare, or openai-gpt-image-2.5-sunburst. Validated against tenant allowedModels
resolution_tier	string	No	Gemini output tier: 0.5k, 1k, 2k, or 4k. Lite is fixed at 1K; higher tiers require Nano Banana 2 or Pro
use_google_search	boolean	No	Enable Google Search grounding for Nano Banana 2 or Pro
enable_thinking	boolean	No	Enable Gemini thinking mode for Lite, Nano Banana 2, or Pro
size	string	No	OpenAI models only: auto or WIDTHxHEIGHT meeting OpenAI size constraints
output_format	string	No	OpenAI models only: png (default), jpeg, webp
quality	string	No	OpenAI models only: low, medium, high, auto (default); xhigh and max require GPT Image 2.5
output_compression	int	No	OpenAI models only (jpeg/webp): 0–100
background	string	No	OpenAI models only: auto (default) or opaque; GPT Image 2.5 also supports transparent with png or webp
moderation	string	No	OpenAI models only: auto (default) or low
system_instruction	string	No	Style guidance (max 512 chars)
style_preset_id	number	No	Apply saved style preset by ID
style_preset_name	string	No	Apply saved style preset by name
reference_images	string[]	No	Additional reference R2 keys (advanced; usually provided by the frontend)
reference_group_id	number	No	Use a saved reference group by ID
reference_group_ids	number[]	No	Use multiple reference groups (1-5)
reference_group_name	string	No	Use a reference group by name
reference_mode	string	No	'style' for style transfer or 'add' to include elements in composition
session_id	string	No	Override session grouping
character_id	number	No	Single character ID for consistent generation
character_ids	number[]	No	Array of character IDs (1-5) for multi-character scenes
product_id	number	No	Single product reference ID
product_ids	number[]	No	Array of product IDs (1-6) for product placement
image_to_edit_id	number	No	If set, edits that image instead of generating a new one

Aspect Ratios

Value	Dimensions	Use Case
square	1:1	Social media posts
portrait	3:4	Mobile wallpapers
landscape	4:3	Desktop backgrounds
16:9	Widescreen	Presentations
9:16	Vertical	Stories, TikTok

Also accepts numeric ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.

Models

Default Model

gemini-flash-lite-image (Nano Banana 2 Lite) is the current default — fastest, lowest-cost, and optimized for 1K generation/editing. Override per request via model_id when you need multi-reference strength, 2K/4K, grounding, or OpenAI-specific output controls.

Model	Provider	Description
gemini-flash-lite-image	Gemini 3.1 Flash Lite	Fastest (~2s), lowest cost, 1K output (default)
gemini-flash-image	Gemini 3.1 Flash	Versatile Flash model, 2K/4K tiers, stronger multi-reference workflows
gemini-pro-image	Gemini 3 Pro	Best Gemini quality, Google Search grounding, 1K/2K/4K tiers
openai-gpt-image-2	OpenAI GPT Image 2	Best-in-class text rendering, prompt adherence, quality/format controls
openai-gpt-image-2.5-flare	OpenAI GPT Image 2.5 Flare	Fast everyday generation; adds xhigh/max quality and transparent backgrounds (details)
openai-gpt-image-2.5-sunburst	OpenAI GPT Image 2.5 Sunburst	Precise generation and editing; same controls as Flare (details)

Provider Capability Comparison

Feature	Lite	Flash	Pro	OpenAI GPT Image 2	OpenAI GPT Image 2.5 (Flare, Sunburst)
Resolution	1K	0.5K, 1K, 2K, 4K	1K, 2K, 4K	Any size meeting constraints (≤3,840px edge, ×16, ≤3:1)	Same as GPT Image 2
Reference Images	14	14	14 (6 high fidelity)	16	16
Text Rendering	Basic	Strong	Advanced (multilingual)	Best-in-class	Best-in-class
Google Search Grounding	No	Yes	Yes	No	No
Thinking Mode	Yes	Yes	Yes	Not exposed	Not exposed
Output Formats	PNG	PNG	PNG	PNG, JPEG, WebP + compression	PNG, JPEG, WebP + compression
Quality Levels	auto	auto	auto	low / medium / high / auto	low / medium / high / xhigh / max / auto
Transparent Background	No	No	No	No	Yes
Default Timeout	30s	60s	120s	240s	240s

Pro Exclusive Features:

• Text & Infographics (SOTA text rendering)
• Viral Thumbnails (identity + text + graphics)
• Storyboarding (multi-scene sequential art)
• Structural Control (sketch-to-final)
• 2D↔3D Translation (floor plans to renders)
• High-Fidelity Upscaling (150x150 → 4K)
• Photo Restoration (fix damaged photos)
• 360 Turnaround (multiple angles from single reference)
• Google Search Grounding (live data citations)

OpenAI gpt-image-2 Exclusive Features:

• Best-in-class small text and dense layouts (infographics, marketing copy)
• Quality tiers (low / medium / high) for explicit cost control
• Native JPEG/WebP output with output_compression
• Broad aspect-ratio support including 21:9 cinematic and 4:5 / 5:4 social formats

Learn Pro Best Practices → · OpenAI gpt-image-2 deep-dive →

Example

Generate a sunset over mountains, landscape aspect ratio

Equivalent tool call:

{
  "tool": "generate_image",
  "params": {
    "prompt": "a beautiful sunset over mountains with golden light streaming through purple clouds",
    "aspect_ratio": "landscape",
    "negative_prompt": "blurry, low quality"
  }
}

Response

Generated 1 image:

**Image #342**
- URL: https://pub-xxx.r2.dev/tenant/2024-01-15/generate-abc123.png
- Thumbnail: https://pub-xxx.r2.dev/tenant/2024-01-15/generate-abc123-thumb.jpg
- Dimensions: 1024x768
- Size: 2.3 MB
- SynthID: Yes

Using Style Presets

Reference a saved style preset:

{
  "tool": "generate_image",
  "params": {
    "prompt": "a mountain landscape",
    "style_preset_name": "Cinematic"
  }
}

The preset's prompt, negative_prompt, and system_instruction are automatically applied.

Using Reference Groups

Reference groups let you save a set of images and reuse them in future generations:

{
  "tool": "generate_image",
  "params": {
    "prompt": "a clean studio shot of a sneaker on white background",
    "reference_group_name": "Brand Style",
    "reference_mode": "style"
  }
}

Groups can be combined with characters/products, and you can pass up to 5 groups per request.

Editing via image_to_edit_id

If you want to edit a specific image but still use the generate_image surface (e.g., apply style presets or reference groups), pass image_to_edit_id:

{
  "tool": "generate_image",
  "params": {
    "image_to_edit_id": 342,
    "prompt": "make the background darker and more dramatic"
  }
}

Character & Product Integration

Generate images with characters and/or products for consistent branding:

Single Character:

{
  "tool": "generate_image",
  "params": {
    "prompt": "at a coffee shop working on laptop",
    "character_id": 19,
    "aspect_ratio": "16:9"
  }
}

Multiple Characters (2-5):

{
  "tool": "generate_image",
  "params": {
    "prompt": "having a team meeting in modern office",
    "character_ids": [19, 20],
    "aspect_ratio": "landscape"
  }
}

Character + Product Combined:

{
  "tool": "generate_image",
  "params": {
    "prompt": "at a product photoshoot",
    "character_ids": [19, 20],
    "product_ids": [2],
    "aspect_ratio": "16:9"
  }
}

Limits (Gemini 3 Pro):

Resource	Maximum
Characters per scene	5
Products per scene	6
Total reference images	14

WARNING

Cannot mix singular and array forms (e.g., character_id + character_ids). Use one or the other.

---

generate_poster

Generate posters, flyers, covers, and campaign assets from structured brief fields. This tool uses the same storage, session, quota, and provider pipeline as generate_image, but adds a curated poster-style picker and poster-specific prompt builder.

When style is omitted, Go Bananas auto-picks from the poster catalog. Text-heavy poster work defaults to openai-gpt-image-2 when the tenant allowlist includes it; otherwise it uses the tenant default model.

Parameters

Parameter	Type	Required	Description
brief	string	Yes	Client brief for the poster
style	string	No	Style ID from list_poster_styles
title	string	No	Main headline or masthead
subtitle	string	No	Tagline, date, issue line, or support copy
body	string	No	Supporting details, feature list, or cover lines
footer	string	No	CTA, venue, billing block, or credit line
subject	string	No	Main visual subject; defaults to the brief
palette	string[]	No	Strict hex palette override
template_image_id	number	No	Existing poster image to use as layout reference
hero_image_id	number	No	Existing image to use as the main hero photo/reference
logo_image_id	number	No	Existing image to use as an exact logo/wordmark reference
reference_image_ids	number[]	No	Additional existing image IDs in order
n	number	No	Number of poster variations, 1-4
aspect_ratio	string	No	Override the style default
quality	string	No	OpenAI quality: low, medium, high, or auto

Example

{
  "tool": "generate_poster",
  "params": {
    "brief": "open house flyer for a modern hillside villa",
    "title": "1414 Ridge Lane",
    "subtitle": "Open Sunday 1-4 PM",
    "body": "4 BD / 3.5 BA / vineyard views",
    "footer": "Private showings available",
    "palette": ["#0E3B2E", "#C9A96E", "#FAFAF6"]
  }
}

Reference Order

When image IDs are supplied, references are ordered as:

1. template_image_id
2. hero_image_id
3. reference_image_ids
4. logo_image_id

This makes template replication and brand-safe poster generation predictable.

list_poster_styles

List all curated poster styles available to generate_poster.

{
  "tool": "list_poster_styles",
  "params": {}
}

Common style IDs include luxury-real-estate, emerald-nocturne, tech-conf-darkmode, indie-gig-riso, corporate-report, sports-action-hero, and minimal-tech-keynote.

---

request_higgsfield_video

Submit an async Higgsfield image-to-video request from an existing Go Bananas image ID or a public image URL. This starts a provider-side video job and returns a requestId; use get_higgsfield_video_status to poll for the completed MP4 URL.

Cost control

This tool can spend Higgsfield credits. Configure a tenant higgsfield provider credential first, then start with 5-second 720p jobs before increasing model, duration, or resolution.

Parameters

Parameter	Type	Required	Description
image_id	number	No	Existing Go Bananas image ID to animate
image_url	string	No	Public image URL to animate
prompt	string	Yes	Motion prompt, max 1000 characters
model_id	string	No	Higgsfield model ID; defaults to higgsfield-ai/dop/standard
duration	number	No	5 or 10 seconds
resolution	string	No	480p, 720p, 1080p, or 4K
webhook_url	string	No	Optional public webhook endpoint

Provide exactly one of image_id or image_url.

Example

{
  "tool": "request_higgsfield_video",
  "params": {
    "image_id": 6481,
    "prompt": "Slow cinematic push-in, subtle atmospheric motion, polished commercial look",
    "duration": 5,
    "resolution": "720p"
  }
}

get_higgsfield_video_status

Poll a Higgsfield async video request.

{
  "tool": "get_higgsfield_video_status",
  "params": {
    "request_id": "request-123"
  }
}

Completed jobs return videoUrl when Higgsfield has produced the MP4.

---

edit_image

Edit an existing image by its database ID.

Parameters

Parameter	Type	Required	Description
image_id	number	Yes	Database ID of image to edit
prompt	string	Yes	Edit instruction (max 2048 chars)
negative_prompt	string	No	What to avoid
aspect_ratio	string	No	New aspect ratio

Example

Edit image #342: add dramatic storm clouds

Tool call:

{
  "tool": "edit_image",
  "params": {
    "image_id": 342,
    "prompt": "add dramatic storm clouds in the sky"
  }
}

Response

Edited image #342:

**New Image #343**
- URL: https://pub-xxx.r2.dev/tenant/2024-01-15/edit-def456.png
- Parent: #342
- Edit Depth: 1

Edit Lineage

Each edit creates a new image linked to its parent:

#342 (Original)
  └─ #343 (add clouds)
       └─ #344 (make brighter)
            └─ #345 (add birds)

---

edit_uploaded_image

Edit a user-uploaded image. Use after upload_image_for_editing.

Parameters

Parameter	Type	Required	Description
image_id	number	Yes	ID from upload_image_for_editing
edit_prompt	string	Yes	Edit instruction
negative_prompt	string	No	What to avoid
aspect_ratio	string	No	Aspect ratio

Best For

• Adding/removing objects
• Changing colors or styles
• Applying filters or effects
• Style transfer

Not For

• Zooming or cropping
• Changing aspect ratio significantly
• Repositioning main subjects

For those operations, use generate_image with a reference image instead.

Example

{
  "tool": "edit_uploaded_image",
  "params": {
    "image_id": 100,
    "edit_prompt": "remove the background and make it transparent"
  }
}

---

continue_editing

Edit the last image in your session conversationally.

Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Edit instruction
negative_prompt	string	No	What to avoid
aspect_ratio	string	No	New aspect ratio

How It Works

The session tracks your last_image_id:

1. You generate an image -> last_image_id = 342
2. You say "add clouds" -> Tool edits #342, creates #343
3. Session updates -> last_image_id = 343
4. You say "make brighter" -> Tool edits #343, creates #344

Example Conversation

User: Generate a portrait of a businessman
AI: [generates image #342]

User: Make the background darker
AI: [uses continue_editing, creates #343]

User: Add a subtle vignette
AI: [uses continue_editing, creates #344]

Tool Call

{
  "tool": "continue_editing",
  "params": {
    "prompt": "make the background darker and more dramatic"
  }
}

Error: No Image

If no image exists in the session:

{
  "error": {
    "code": "NO_IMAGE_TO_EDIT",
    "message": "No image in current session. Generate an image first."
  }
}

---

get_image_info

Display a native inline thumbnail in supported MCP clients, followed by detailed metadata about the image. If a thumbnail is unavailable or too large, the tool gracefully returns the metadata without an inline preview.

Parameters

Parameter	Type	Required	Description
image_id	number	Yes	Database ID of image

Example

{
  "tool": "get_image_info",
  "params": {
    "image_id": 342
  }
}

Response

The MCP response contains an image content block for the thumbnail before the text metadata:

{
  "content": [
    {
      "type": "image",
      "data": "<base64 thumbnail>",
      "mimeType": "image/webp"
    },
    {
      "type": "text",
      "text": "Image #342: 1024x768, generate, https://gobananasai.com/public/images/..."
    }
  ]
}

Clients that do not render image content blocks can still use the URL in the text result.

Image #342 Details:

**URLs**
- Full: https://pub-xxx.r2.dev/tenant/2024-01-15/generate-abc.png
- Thumbnail: https://pub-xxx.r2.dev/tenant/2024-01-15/generate-abc-thumb.jpg

**Metadata**
- Dimensions: 1024x768
- Size: 2.3 MB
- Format: PNG
- Created: 2024-01-15 14:32:00
- Operation: generate
- Session: sess_abc123

**Prompt**
"a beautiful sunset over mountains with golden light"

**Edit History**
- This is the original image
- Has 3 child edits: #343, #344, #345

**Generation Settings**
- Model: gemini-flash-image
- Aspect Ratio: landscape
- SynthID: Yes

---

get_session_history

List all images generated in the current session.

Parameters

Parameter	Type	Required	Description
limit	number	No	Max images to return (default: 50, max: 200)
offset	number	No	Pagination offset (default: 0)

Example

{
  "tool": "get_session_history",
  "params": {
    "limit": 20
  }
}

Response

Session History (12 images):

1. #353 - "add more clouds" (edit)
   2024-01-15 15:45 | 1024x768 | 2.1 MB

2. #352 - "make colors vibrant" (edit)
   2024-01-15 15:40 | 1024x768 | 2.0 MB

3. #351 - "sunset mountains" (generate)
   2024-01-15 15:35 | 1024x768 | 2.3 MB

... (showing 12 of 12)

Session Stats:
- Total Images: 12
- Generations: 4
- Edits: 8
- Current Image: #353

---

search_images

Search across all your images with filters.

Parameters

Parameter	Type	Required	Description
filters	object	No	Search filters
limit	number	No	Max results (default: 15, max: 50)
offset	number	No	Pagination offset
sort_order	string	No	"newest" or "oldest"

Filter Options

{
  "filters": {
    "prompt_substring": "sunset",
    "session_id": "sess_abc123",
    "operation_type": "generate",
    "aspect_ratio": "landscape",
    "created_after": "2024-01-01T00:00:00Z",
    "created_before": "2024-01-31T23:59:59Z",
    "style_preset_id": 5,
    "style_preset_name": "Cinematic",
    "product_reference_id": 10,
    "product_reference_name": "Water Bottle",
    "has_synthid": true
  }
}

Example: Recent Sunsets

{
  "tool": "search_images",
  "params": {
    "filters": {
      "prompt_substring": "sunset",
      "created_after": "2024-01-01T00:00:00Z"
    },
    "limit": 20,
    "sort_order": "newest"
  }
}

Response

Found 45 images matching "sunset":

1. #450 - "dramatic sunset with clouds"
   2024-01-15 | landscape | generate

2. #423 - "sunset over ocean"
   2024-01-14 | square | generate

3. #401 - "desert sunset silhouette"
   2024-01-12 | 16:9 | generate

... showing 20 of 45

[Page 1 of 3]

Search Tips

• Use prompt_substring for text matching
• Combine filters for precise results
• Use date ranges for time-based searches
• Filter by operation_type for only generates or edits

---

upload_image_for_editing

Upload an external image for editing.

Parameters

Parameter	Type	Required	Description
image_url	string	Yes	Public URL to image
file_name	string	No	Original filename
mime_type	string	No	MIME type (auto-detected)

Workflow

1. Upload image to imgur.com or imgbb.com
2. Copy direct image URL
3. Call upload_image_for_editing
4. Use returned image_id with edit_uploaded_image

Example

{
  "tool": "upload_image_for_editing",
  "params": {
    "image_url": "https://i.imgur.com/abc123.jpg"
  }
}

Response

Image uploaded successfully!

Image ID: 500
- Stored in R2
- Ready for editing

Use edit_uploaded_image with image_id: 500 to edit this image.

Supported Formats

• PNG
• JPEG
• WebP

TIP

Use PNG or JPEG for best results. WebP may have compatibility issues with some edit operations.

---

batch_generate

Generate several images in one request. The whole batch takes a single slot in the generation queue and runs up to 4 provider calls at a time, so it is much faster than calling generate_image repeatedly. Each item succeeds or fails on its own.

Parameters

Parameter	Type	Required	Description
items	object[]	Yes	1–8 items. Each needs a prompt and can override the defaults below
items[].prompt	string	Yes	Text prompt for this image (max 16384 chars)
items[].model_id	string	No	Model for this item
items[].resolution_tier	string	No	Gemini tier for this item: 0.5k, 1k, 2k, 4k (Lite is fixed at 1K)
items[].aspect_ratio	string	No	Aspect ratio for this item
items[].negative_prompt	string	No	Negative prompt (max 1024 chars)
items[].system_instruction	string	No	System instruction (max 512 chars)
items[].style_preset_name	string	No	Saved style preset to apply (max 128 chars)
defaults	object	No	Shared model_id, resolution_tier, aspect_ratio, negative_prompt, system_instruction and style_preset_name for every item; per-item values win
session_id	string	No	Session handle for grouping the generated images

Example

{
  "tool": "batch_generate",
  "params": {
    "defaults": { "aspect_ratio": "16:9", "style_preset_name": "Cinematic" },
    "items": [
      { "prompt": "a lighthouse at dawn" },
      { "prompt": "a lighthouse in a storm" },
      { "prompt": "a lighthouse at night", "aspect_ratio": "9:16" }
    ]
  }
}

Response

Batch: 3/3 generated (41250ms)
  #1: https://.../image-1.png (ID: 601)
  #2: https://.../image-2.png (ID: 602)
  #3: https://.../image-3.png (ID: 603)

A failed item is listed as #N: FAILED - <reason> while the others still return.

Notes

• The session's last image becomes the last successful item, so continue_editing works straight after a batch.
• Run check_quota with estimated_images first for large or high-cost batches.
• The REST equivalent is POST /api/images/batch.

---

upload_media

Upload a video, audio or image file and get back a durable, public URL that does not expire. The original file extension is kept (an .mp4 in stays an .mp4 URL out) and the bytes are stored as-is, with no transcoding. Use it to host reference media for external video or voice tools, such as Seedance reference videos.

Parameters

Parameter	Type	Required	Description
file_path	string	One of file_path / media_url	Local file path. Only works through the STDIO proxy (gobananas-mcp), which reads the file and uploads it for you
media_url	string	One of file_path / media_url	HTTP or HTTPS URL pointing directly at the media file
file_name	string	No	Original filename, used to preserve the extension
mime_type	string	No	MIME type; inferred from the extension when omitted

Supported formats: video (mp4, mov, webm), audio (mp3, wav, m4a, aac), image (png, jpg, jpeg, webp, gif). Maximum 200 MB.

Example

{
  "tool": "upload_media",
  "params": {
    "media_url": "https://example.com/clips/voice-clip.mp4"
  }
}

Response

Media uploaded successfully! Media ID: 77

Public URL (durable, no expiry): https://.../voice-clip-3f9a1c.mp4

Details:
- Kind: video
- Format: mp4
- MIME type: video/mp4
- Size: 2048.00 KB

Notes

• A remote connection (https://mcp.gobananasai.com) cannot read files on your machine, so a file_path sent straight to the server is rejected. Use media_url, the STDIO proxy, or the REST endpoint POST /api/media/upload.
• To edit an image rather than host it, use upload_image_for_editing.

Next Steps

• Style Preset Tools →
• Character Tools →
• Product Tools →