Image Generation Tools

Tools for creating and editing images via MCP.

Pro Prompting Tips

Golden Rules from Google DeepMind:

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

Advanced Techniques

Negative Prompting - Tell the model what NOT to include:

json

{
  "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:

json

{
  "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.1, Go Bananas! Pro, OpenAI GPT Image 2, or GPT Image 2.6 / 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-nano-banana-2.1`, `gemini-pro-image`, `openai-gpt-image-2`, `openai-gpt-image-2.6-flare`, `openai-gpt-image-2.6-sunburst`, `openai-gpt-image-2.5-flare`, or `openai-gpt-image-2.5-sunburst`. Validated against tenant `allowedModels`. `gemini-flash-image` is a deprecated alias of `gemini-nano-banana-2.1`
`resolution_tier`	string	No	Gemini output tier: `1k`, `2k`, or `4k`. Lite is fixed at 1K; higher tiers require Nano Banana 2.1 or Pro. No current model offers `0.5k`
`use_google_search`	boolean	No	Enable Google Search grounding for Nano Banana 2.1 or Pro
`enable_thinking`	boolean	No	Enable Gemini thinking mode for Lite, Nano Banana 2.1 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 or 2.6
`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 and 2.6 also support `transparent` with png or webp
`moderation`	string	No	OpenAI models only: `auto` (default) or `low`
`complexity`	string	No	GPT Image 2.6 only: `low`, `medium` or `high` planning effort, separate from `quality`. Omitted, 2.6 uses `high`. Other OpenAI models are refused (`-32602`); Gemini models ignore it
`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
`project`	string	No	Project to file the new images under, only when the user names one (`"none"` for no project); otherwise, with the local connector (`gobananas-mcp` 1.4.0 or later), the project of the folder you work in. Every tool that makes images takes it (Projects and tags)
`tags`	string[]	No	Tags to add to the new images, up to 10
`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
`reference_assets`	object[]	No	Typed references (1-16), each with a `role` and one source. A `character` reference can also take `scope`: `face`, `wardrobe` or `full` (default). See Reference roles
`camera_look`	string	No	A built-in real-camera look; see Camera looks. Not with `enhance_prompt` or `image_to_edit_id`
`reference_sheet`	string	No	A built-in identity plate: `face-plate`, `outfit-plate` or `three-panel`; see Reference sheets. Not with `camera_look`, `enhance_prompt` or `image_to_edit_id`

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-nano-banana-2.1`	Nano Banana 2.1	Versatile model, 1K/2K/4K tiers, stronger multi-reference workflows, Google Search grounding. Replaces Nano Banana 2 (`gemini-flash-image` is an alias)
`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.6-flare`	OpenAI GPT Image 2.6 Flare	Fast generation and edits; adds `xhigh`/`max` quality and transparent backgrounds (details)
`openai-gpt-image-2.6-sunburst`	OpenAI GPT Image 2.6 Sunburst	Detailed generation and precise edits; same controls as Flare (details)
`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	Nano Banana 2.1	Pro	OpenAI GPT Image 2	OpenAI GPT Image 2.5 / 2.6 (Flare, Sunburst)
Resolution	1K	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	Not measured yet	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)
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:

json

{
  "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:

json

{
  "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:

json

{
  "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.

Camera Looks

For a photo that should look like a real camera capture, a candid or amateur shot, or a still for a video's first frame, pass camera_look. Describe only the subject, action and setting; the look supplies the camera, lens and light, so leave out your own camera or lighting words such as "85mm", "golden hour" or "cinematic". They compete with the look and can override it.

json

{
  "tool": "generate_image",
  "params": {
    "prompt": "A bike courier in a yellow raincoat laughs mid-jump over a puddle beside a bus shelter.",
    "camera_look": "disposable-flash"
  }
}

Look	Ratio hint	What it gives
`disposable-flash`	1:1	single-use film camera, direct flash, black background, warm grain
`skate-fisheye`	1:1	fisheye lens at knee height, curved horizon, on-camera flash
`old-phone-selfie`	9:16	2010s phone front camera held at arm's length; best with people, since with an animal or object it adds a person holding the phone
`camcorder-still`	16:9	paused frame from an early-2000s home video; a good video first frame
`point-and-shoot-night`	16:9	compact digital camera at night, tilted horizon, flash, JPEG noise
`street-candid-35mm`	16:9	unposed daylight shot on 35mm film from a few metres away
`security-camera`	16:9	fixed high-corner CCTV still, near-monochrome
`instant-film`	1:1	square instant-camera snapshot, soft focus, faded colour

The look's camera sentence goes first, ahead of any scene, style preset or reference wording, and its lighting and texture sentences follow your prompt; a reference_assets roles block still comes last, so a character keeps its likeness. The look's negative prompt and ratio hint apply only when the request, its scene, style preset and character leave them unset. A synchronous response's metadata.camera_look names the look; async job status does not, but each image's stored prompt includes the look's sentences. It cannot be combined with enhance_prompt or image_to_edit_id, and it counts towards the model's prompt limit.

Reference Sheets

To make identity plates for a recurring character, pass reference_sheet. A plate is a character picture with flat shadowless light on an even 18% grey. A later image or video copies the person from it, and the scene it is used in sets the light. Describe only the person and the outfit; the sheet supplies the framing, pose, light and background.

Sheet	Ratio hint	What it gives
`face-plate`	1:1	tight chest-up identity portrait, square to the lens, flat light on 18% grey
`outfit-plate`	9:16	full-body front view, standing square, flat light on 18% grey
`three-panel`	16:9	headless full-body front, full-body rear and chest-up face in one wide frame, flat light on 18% grey

Build a kit in this order:

face-plate, from text.
outfit-plate, with the face plate as a character reference with scope: "face".
three-panel, with the face plate (scope: "face") and the outfit plate (scope: "wardrobe"):

json

{
  "tool": "generate_image",
  "params": {
    "prompt": "A woman in her thirties with a short ash-blonde crop and a silver ring in the ear on the right side of the picture, in an olive field jacket.",
    "reference_sheet": "three-panel",
    "reference_assets": [
      { "role": "character", "image_id": 101, "scope": "face" },
      { "role": "character", "image_id": 102, "scope": "wardrobe" }
    ]
  }
}

Name a marker by its side of the picture, as above: "her left ear" can come back mirrored. Reference roles explains what scope tells the model.

The sheet's layout sentence goes first, ahead of any scene, style preset or reference wording, and its lighting and backdrop sentences follow your prompt; a reference_assets roles block still comes last. The sheet's negative prompt and ratio hint apply only when the request, its scene, style preset and character leave them unset. A synchronous response's metadata.reference_sheet names the sheet; async job status does not, but each image's stored prompt includes the sheet's sentences. It cannot be combined with camera_look, enhance_prompt or image_to_edit_id, and it counts towards the model's prompt limit. batch_generate and generate_with_subscription take no references, so use them only for a face-plate.

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:

json

{
  "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:

json

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

Multiple Characters (2-5):

json

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

Character + Product Combined:

json

{
  "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.

preview_generation

Shows what generate_image would send, without making an image. Use it to check a request before spending on it: the final prompt after style presets, scenes, characters, products, reference_assets roles, camera_look and reference_sheet are applied, plus the model, aspect ratio, how many reference pictures each source adds, and a quota check with an estimated cost. It calls no image model, saves nothing and does not count against the monthly quota.

Parameters

The same as generate_image, except client_request_id, generation_lane, project and tags, which only matter when an image is made. It picks the model as generate_image does (model_id, else the first character's preferred model and resolution tier, else the workspace default) and refuses what generate_image refuses: a prompt or style preset is required, camera_look with enhance_prompt is refused, and so are a ratio the model cannot make and an image_to_edit_id that is not in the workspace.

Example

json

{
  "tool": "preview_generation",
  "params": {
    "prompt": "A courier laughs mid-jump over a puddle",
    "camera_look": "disposable-flash",
    "reference_assets": [{ "role": "character", "character_id": 3, "scope": "face" }]
  }
}

Response

A text summary, and the same fields as structuredContent:

Field	Description
`resolvedPrompt`	The prompt the image model would get
`resolvedNegativePrompt`, `resolvedSystemInstruction`, `resolvedAspectRatio`	What the request, scene, style preset, character, camera look or reference sheet set
`resolvedModelId`, `resolvedModelName`, `requestedCount`	Model and number of images
`resolvedCharacterNames`, `resolvedProductNames`, `resolvedSceneNames`, `resolvedReferenceGroupNames`	The saved items it used (with their ids)
`referenceImageCounts`	Reference pictures from each source, and the total
`quotaCheck`	`canGenerate`, reasons, warnings and the estimated cost, as from `check_quota`
`warnings`	Notes such as `enhance_prompt` not being run, or the workspace having no key for the chosen model
`lane`	Always `provider`

What it does not show

enhance_prompt is not run, because it rewrites the prompt differently every time; the preview shows the prompt before enhancement and says so.
It covers the workspace's own keys only. An OAuth generate_image call may still go to a connected ChatGPT subscription.
An image_url reference is checked as an address but not downloaded, so a picture that fails to download, or is under 512×512, is found only when you generate.

OAuth permission: images:read, plus the read permission for any saved character, product, scene, style preset or reference group the request names. REST clients can use POST /api/images/resolve, which takes the same body, picks the model the same way and does run enhance_prompt.

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. Without model_id, a poster uses openai-gpt-image-2.6-flare when the tenant allowlist includes it and the tenant has an active OpenAI key, then openai-gpt-image-2 on the same terms, otherwise the tenant default model. A poster with character_id tries the face default, also openai-gpt-image-2.6-flare, first.

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

json

{
  "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:

template_image_id
hero_image_id
reference_image_ids
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.

json

{
  "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

json

{
  "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.

json

{
  "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:

json

{
  "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

json

{
  "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:

You generate an image -> last_image_id = 342
You say "add clouds" -> Tool edits #342, creates #343
Session updates -> last_image_id = 343
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

json

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

Error: No Image

If no image exists in the session:

json

{
  "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

json

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

Response

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

json

{
  "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-nano-banana-2.1
- 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

json

{
  "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. Each result shows its project and tags.

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"

json

{
  "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,
    "project": "Brand Refresh",
    "tags": ["hero", "draft"]
  }
}

project is a name or key, or "none" for images without a project. An image must have every tag in tags (up to 10).

Example: Recent Sunsets

json

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

Response

One line per image, with its project and tags when it has either:

Found 45 images (showing 20). Use get_image_info on any ID for details.
#450 (Brand Refresh · hero, draft)
#423 (Brand Refresh)
#401 (no project · sunset)
#398
...

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
Filter by project and tags to find one campaign's images

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

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

Example

json

{
  "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: `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); `""` counts as unset, so `defaults.negative_prompt` still applies
`items[].system_instruction`	string	No	System instruction (max 512 chars); `""` counts as unset, so `defaults.system_instruction` still applies
`items[].style_preset_name`	string	No	Saved style preset to apply (max 128 chars); `""` counts as unset, so `defaults.style_preset_name` still applies
`items[].camera_look`	string	No	Built-in real-camera look for this item (see camera looks); overrides `defaults.camera_look`
`items[].reference_sheet`	string	No	Built-in identity plate for this item (see reference sheets); overrides `defaults.reference_sheet`. Batch items take no references, so use it for a `face-plate`
`defaults`	object	No	Shared `model_id`, `resolution_tier`, `aspect_ratio`, `negative_prompt`, `system_instruction`, `style_preset_name`, `camera_look` and `reference_sheet` for every item; per-item values win
`session_id`	string	No	Session handle for grouping the generated images

Example

json

{
  "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.
With camera_look, each item is written and filled as generate_image does it: the look's negative and ratio apply only when the item, the defaults and the style preset set none. Each such item gets a Camera look: <id> line under its image line, and a look that pushes any item over the model's prompt limit refuses the whole batch before anything is generated.
reference_sheet works the same way, with a Reference sheet: <id> line. An item with both a sheet and a camera look, from the item or the defaults, refuses the whole batch.
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

json

{
  "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.

start_generation

Start a generate_image request as a durable job and get an execution_id back straight away. The job keeps running if your client disconnects. Use it for slow models, or when your client times out on long tool calls. The same jobs are available over REST at /api/generations/*; see Async generation.

Parameters

Every generate_image parameter, one request per job, plus:

Parameter	Type	Required	Description
`idempotency_key`	string	No	Up to 200 characters. Repeating a call with the same key returns the same job instead of starting a new one
`sync_timeout_ms`	number	No	Wait up to this long (max 25000) for the job to finish. If it finishes in time the images come back inline

At most 3 unfinished jobs per workspace. A fourth start is rejected until one finishes or is cancelled.

Example

json

{
  "tool": "start_generation",
  "params": {
    "prompt": "a lighthouse at dusk, oil painting",
    "model_id": "gemini-pro-image",
    "idempotency_key": "lighthouse-001"
  }
}

The response includes execution_id, status, replayed (true when the key matched an existing job) and, while the job is unfinished, a next_action hint to poll get_generation_status.

get_generation_status

Get the status, progress and log entries of a job you started. Once the status is completed, the response includes the images.

Parameter	Type	Required	Description
`execution_id`	string	Yes	The `execution_id` from `start_generation`

Status is one of pending, running, completed, failed or cancelled. Poll until it is completed, failed or cancelled.

Only the API key, or the OAuth user and client, that started the job can see it. Anyone else gets "Generation not found".

cancel_generation

Cancel a job you started. A job that has not been dispatched never runs; a running job is stopped and nothing is stored.

Parameter	Type	Required	Description
`execution_id`	string	Yes	The `execution_id` from `start_generation`

Returns cancel_requested: false with a message when the job had already finished.

Image Generation Tools ​

generate_image ​

Parameters ​

Aspect Ratios ​

Models ​

Provider Capability Comparison ​

Example ​

Response ​

Using Style Presets ​

Using Reference Groups ​

Camera Looks ​

Reference Sheets ​

Editing via image_to_edit_id ​

Character & Product Integration ​

preview_generation ​

Parameters ​

Example ​

Response ​

generate_poster ​

Parameters ​

Example ​

Reference Order ​

list_poster_styles ​

request_higgsfield_video ​

Parameters ​

Example ​

get_higgsfield_video_status ​

edit_image ​

Parameters ​

Example ​

Response ​

Edit Lineage ​

edit_uploaded_image ​

Parameters ​

Best For ​

Not For ​

Example ​

continue_editing ​

Parameters ​

How It Works ​

Example Conversation ​

Tool Call ​

Error: No Image ​

get_image_info ​

Parameters ​

Example ​

Response ​

get_session_history ​

Parameters ​

Example ​

Response ​

search_images ​

Parameters ​

Filter Options ​

Example: Recent Sunsets ​

Response ​

Search Tips ​

upload_image_for_editing ​

Parameters ​

Workflow ​

Example ​

Response ​

Supported Formats ​

batch_generate ​

Parameters ​

Example ​

Response ​

Notes ​

upload_media ​

Parameters ​

Example ​

Response ​

Notes ​

start_generation ​

Parameters ​

Example ​

get_generation_status ​

cancel_generation ​

Next Steps ​

Image Generation Tools

generate_image

Parameters

Aspect Ratios

Models

Provider Capability Comparison

Example

Response

Using Style Presets

Using Reference Groups

Camera Looks

Reference Sheets

Editing via `image_to_edit_id`

Character & Product Integration

preview_generation

Parameters

Example

Response

generate_poster

Parameters

Example

Reference Order

list_poster_styles

request_higgsfield_video

Parameters

Example

get_higgsfield_video_status

edit_image

Parameters

Example

Response

Edit Lineage

edit_uploaded_image

Parameters

Best For

Not For

Example

continue_editing

Parameters

How It Works

Example Conversation

Tool Call

Error: No Image

get_image_info

Parameters

Example

Response

get_session_history

Parameters

Example

Response

search_images

Parameters

Filter Options

Example: Recent Sunsets

Response

Search Tips

upload_image_for_editing

Parameters

Workflow

Example

Response

Supported Formats

batch_generate

Parameters

Example

Response

Notes

upload_media

Parameters

Example

Response

Notes

start_generation

Parameters

Example

get_generation_status

cancel_generation

Next Steps