switch

Generate Image

generate_image

Generate one or more Switch images with one of four models: GPT Image 2.5, Switch Pro, Switch Ultra or Nano Banana 2. Nothing older is offered or accepted (no old Nano Banana Pro, no GPT Image 2, no Switch Model). Auto-routes by subject when model is omitted: GPT Image 2.5 by default and for typography, screens and storyboards, Switch Pro for swimwear/beach, Switch Ultra for sexier content or face-fidelity work. Nano Banana 2 is never auto-picked, only used when named. Counts <= 8 render inline in chat; counts > 8 queue to your Switch Studio with progress polling. All images persist to your Studio library and folder. Pass an optional style (e.g. "wellness/warm_amber_tropical", "high_fashion_editorial/testino_glossy", "movie_scene/neon_noir_action") to apply a curated photographic stack from the apply_* skill tools.

Input Schema

TableJSON Schema

Name	Required	Description
`count`	No	How many images to generate. Default 4. <= 8 returns inline, > 8 queues to Studio. Beta limit: max 50 per request — larger asks are capped at 50 and the response says so.
`model`	No	Optional explicit model: GPT Image 2.5, Switch Pro, Switch Ultra or Nano Banana 2. Nothing else is accepted. If omitted, auto-routed to GPT Image 2.5, Switch Pro or Switch Ultra by subject (see tool description).
`style`	No	Optional curated style stack from the apply_* skill tools. Format "<skill>/<style_key>", e.g. "wellness/warm_amber_tropical" or "high_fashion_editorial/leibovitz_painterly".
`subject`	Yes	Plain-English description of what to generate. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony, model wearing a robe".
`folder_name`	No	Optional Switch Studio folder name. Auto-created if missing. Defaults to the chat-derived title.
`aspect_ratio`	No	Image aspect ratio. Default 9:16 (vertical, social-friendly).
`real_photo_look`	No	Optional. Adds the casual real-photo texture (film grain, amateur iPhone feel). OFF by default — only set true when the user asks for the realistic, unpolished look.
`face_reference_ids`	No	Face reference asset ids from upload_reference_asset (frame_type "face"). The ONLY way to use a face/likeness reference. Each id is verified server-side (your own untouched original + identity verification) before anything generates or is charged; a URL or generic upload here is rejected.
`reference_image_urls`	No	Optional public image URLs used as GENERIC references (products, scenery, outfits, style). These are never treated as face references — for a person's face/likeness use face_reference_ids.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`asset`	No
`images`	No
`_widget`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 23, 2026

changedInput schema / properties / model / description

Previous value: -"Optional explicit model. If omitted, auto-routed based on subject content (see tool description)."New value: +"Optional explicit model: GPT Image 2.5, Switch Pro, Switch Ultra or Nano Banana 2. Nothing else is accepted. If omitted, auto-routed to GPT Image 2.5, Switch Pro or Switch Ultra by subject (see tool description)."

changedInput schema / properties / model / enum

Previous value: -[
-  "Nano Banana 2",
-  "Nano Banana Pro",
-  "Switch Model",
-  "Switch Pro",
-  "Switch Ultra",
-  "GPT Image 2",
-  "GPT Image 2.5",
-  "GPT Image 2.5 Flare",
-  "WAN 2.7"
-]New value: +[
+  "GPT Image 2.5",
+  "Switch Pro",
+  "Switch Ultra",
+  "Nano Banana 2"
+]

Changed1 schema field changedSep 9, 2026

changedInput schema / properties / model / enum

Previous value: -[
-  "Nano Banana 2",
-  "Nano Banana Pro",
-  "Switch Model",
-  "Switch Pro",
-  "Switch Ultra",
-  "GPT Image 2",
-  "WAN 2.7"
-]New value: +[
+  "Nano Banana 2",
+  "Nano Banana Pro",
+  "Switch Model",
+  "Switch Pro",
+  "Switch Ultra",
+  "GPT Image 2",
+  "GPT Image 2.5",
+  "GPT Image 2.5 Flare",
+  "WAN 2.7"
+]

Changed2 schema fields changedJul 15, 2026

addedInput schema / properties / face_reference_ids

Added value: +{
+  "description": "Face reference asset ids from upload_reference_asset (frame_type \"face\"). The ONLY way to use a face/likeness reference. Each id is verified server-side (your own untouched original + identity verification) before anything generates or is charged; a URL or generic upload here is rejected.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / reference_image_urls / description

Previous value: -"Optional public image URLs to use as face/body/scene references."New value: +"Optional public image URLs used as GENERIC references (products, scenery, outfits, style). These are never treated as face references — for a person's face/likeness use face_reference_ids."

Changed1 schema field changedJul 5, 2026

addedInput schema / properties / real_photo_look

Added value: +{
+  "description": "Optional. Adds the casual real-photo texture (film grain, amateur iPhone feel). OFF by default — only set true when the user asks for the realistic, unpolished look.",
+  "type": "boolean"
+}

Changed1 schema field changedJun 13, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "_widget": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "asset": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "images": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedJun 11, 2026

changedInput schema / properties / count / description

Previous value: -"How many images to generate. Default 4. <= 8 returns inline, > 8 queues to Studio."New value: +"How many images to generate. Default 4. <= 8 returns inline, > 8 queues to Studio. Beta limit: max 50 per request — larger asks are capped at 50 and the response says so."

Changed1 schema field changedJun 10, 2026

changedInput schema / properties / model / enum

Previous value: -[
-  "Nano Banana 2",
-  "Nano Banana Pro",
-  "Switch Model",
-  "Switch Pro",
-  "Switch Ultra",
-  "GPT Image 2",
-  "FLUX 2 Pro",
-  "WAN 2.7"
-]New value: +[
+  "Nano Banana 2",
+  "Nano Banana Pro",
+  "Switch Model",
+  "Switch Pro",
+  "Switch Ultra",
+  "GPT Image 2",
+  "WAN 2.7"
+]

First observedJun 5, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=false, so the description carries the burden. It discloses persistence to Studio, queueing behavior for >8, server-side verification of face ids before generating/charging, and the beta cap at 50. These are significant side effects and constraints beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but dense; it front-loads purpose and models, and every sentence contributes unique information. However, the wall-of-text format could be more scannable with bullet points for the routing rules and count behaviors. Size is justified by 9 parameters and complex behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters and an output schema, the description covers model selection, auto-routing, count behavior, persistence, style examples, face reference constraints, and beta limits. There are no obvious gaps an agent would need to invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds substantial meaning: explains auto-routing when model is omitted, count behavior thresholds, style format with concrete examples, face reference verification, and the distinction between face_reference_ids and reference_image_urls. This goes well beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb-resource: 'Generate one or more Switch images'. Names the four models and clearly distinguishes from siblings like generate_video and the apply_* skill tools by focusing on image generation and style application. The scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: auto-routing by model, Nano Banana 2 never auto-picked, count thresholds (<=8 inline, >8 queue), face_reference_ids as the only way for face references, and real_photo_look off by default. This gives clear when/how to use and configures correctly without needing to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All switch tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?