ai.switchapp/switch

Official40 toolsLive

by switchapp

Generate, manage and explore your Switch AI image and video library, scoped to your account.

MCP Server: ai.switchapp/switch

The MCP server ai.switchapp/switch generates, manages, and explores a Switch AI image and video library. Its scope is limited to your account, reflecting that operations and retrieved content are tied to the authenticated user context.

🛠️ Key Features

Generate Switch AI image and video content
Manage an account-scoped Switch AI library
Explore stored Switch AI images and videos

🚀 Use Cases

Creating new image/video assets for your Switch AI library
Organizing and maintaining your account’s existing media
Browsing and reviewing items in your Switch AI library

⚡ Developer Benefits

Exposes functionality via an MCP server with 40 tools
Account-scoped behavior aligns results with your own library

⚠️ Limitations

Limited to managing and exploring content scoped to your account

Captured live from the server via tools/list.

explore_models

Browse the image-generation models available to your Switch account. Returns model id, display name, brand, and credits-per-image so you can pick one before calling generate_image.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

check_balance

Check your daily Switch spending — what you have spent today, your daily limit, and what is remaining. Optionally pass an `estimatedCost` (USD) to also get whether you can afford it.

Parameters1

estimatedCost

number

optional

Optional dollar amount to test against your daily limit.

Raw schema

{
  "type": "object",
  "properties": {
    "estimatedCost": {
      "type": "number",
      "description": "Optional dollar amount to test against your daily limit."
    }
  }
}

list_generations

List your recent and active generation tasks. Returns counts per status (pending / running / completed / failed) plus an array of your tasks with id, status, prompts, model, ref counts, scheduledAt, finishedAt.

Parameters2

status	any	optional	"all" for everything, or array like ["pending","running"]. Default: active + recent.
limit	integer	optional	Default 10. Max 50.

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "description": "\"all\" for everything, or array like [\"pending\",\"running\"]. Default: active + recent."
    },
    "limit": {
      "type": "integer",
      "description": "Default 10. Max 50."
    }
  }
}

show_generation

Get the full detail of one of your generations by task id — prompts, model, ref counts, saved/failed counts, ETA hint, asset ids.

Parameters1

taskId

string

required

Task id from generate_image or list_generations.

Raw schema

{
  "type": "object",
  "properties": {
    "taskId": {
      "type": "string",
      "description": "Task id from generate_image or list_generations."
    }
  },
  "required": [
    "taskId"
  ]
}

check_job_status

Polling-friendly status check for one of your tasks. Returns a slim shape with `status`, `progressPct`, and `eta` so you can poll without refetching the full payload.

Parameters1

taskId

string

required

Task id to check.

Raw schema

{
  "type": "object",
  "properties": {
    "taskId": {
      "type": "string",
      "description": "Task id to check."
    }
  },
  "required": [
    "taskId"
  ]
}

show_media

Display the user's images inline — one or many. Users speak plainly and will NOT know asset ids; never ask for one, resolve it yourself. For "show me" or "show me my last image" call with NO arguments (shows the most recent image). For "show me my last 4 images / my last 10 pictures" pass count=N (returns a clean grid, up to 12). For a specific known image pass assetId. Renders a branded SwitchApp media card with a Download action per result; do not just print URLs. (Videos are not shown here — use list_my_videos and return the newest finished video's view_url, which plays.)

Parameters2

assetId	string	optional	Optional. A specific image id (from list_my_assets, search_my_library, or show_generation). Omit to show the most recent image(s).
count	integer	optional	Optional. How many of the most recent images to show as a grid (default 1, max 12). Use when the user says "my last N images/pictures".

Raw schema

{
  "type": "object",
  "properties": {
    "assetId": {
      "type": "string",
      "description": "Optional. A specific image id (from list_my_assets, search_my_library, or show_generation). Omit to show the most recent image(s)."
    },
    "count": {
      "type": "integer",
      "description": "Optional. How many of the most recent images to show as a grid (default 1, max 12). Use when the user says \"my last N images/pictures\"."
    }
  }
}

list_my_folders

List the folders in your Switch library (id, name, parent). Use this to find an existing folder before move_asset or create_folder.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

list_my_assets

Return asset METADATA only (id, truncated prompt, model, created date), newest first. This does NOT display images and must NOT be used to show pictures — if the user says "show me / display my last image(s)", call show_media instead (it renders them; pass count=N for several). Use list_my_assets only when you need ids/metadata for another tool (e.g. move_asset) or a plain text list.

Parameters1

count

integer

optional

Default 20. Max 50.

Raw schema

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "Default 20. Max 50."
    }
  }
}

search_my_library

Search your library by prompt substring (metadata only — id, prompt, date). Optional folderId scopes to one folder. Only your own assets are returned. This does NOT display images; to show/display results to the user, pass their ids to show_media.

Parameters3

query	string	required
folderId	string	optional
limit	integer	optional	Default 20.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "folderId": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "description": "Default 20."
    }
  },
  "required": [
    "query"
  ]
}

get_my_active_references

Read the user's staged references in Switch Studio. Returns TWO groups: (1) the image-generation reference strip (typed face/body/outfit/scenery/product slots) under `refs`, and (2) the VIDEO-tab references the user staged in the Omni/Image video tabs (the @Image1/@Image2 strip) under `videoReferences`, with usable signed URLs. Call this before generate_image or generate_video whenever the user says "use my refs" or refers to images they staged in Studio (including "the images in my video tab"). To make a video from the video-tab refs, pass videoReferences.imageUrls into generate_video reference_image_urls (and videoUrls into reference_video_urls) in reference-to-video / omni mode. Refs marked alive:false are dead (stored file gone) and are already excluded from the usable url lists. NOTE: a photo the user just attached in THIS chat is in neither group — for that, call upload_media and use its returned url/asset id directly.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

apply_iphone_realism

Phone-shot amateur look — looks like a real person snapped it on their phone. Casual, candid, pore-level real, no professional gloss. Three flavors: digital phone, 35mm film point-and-shoot, or off-duty intimate. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	digital_phone = Sony A7IV + 50mm f/1.4 GM phone-style realism. film_pointshoot = Contax T2 35mm Portra 400. off_duty_intimate = Cass Bird natural-window editorial.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "digital_phone",
        "film_pointshoot",
        "off_duty_intimate"
      ],
      "description": "digital_phone = Sony A7IV + 50mm f/1.4 GM phone-style realism. film_pointshoot = Contax T2 35mm Portra 400. off_duty_intimate = Cass Bird natural-window editorial."
    }
  },
  "required": [
    "style"
  ]
}

apply_movie_scene

Put me in a movie — full cinematic film look matching specific film genres. Choose: neon-noir action thriller, 80s finance excess, comic-book superhero blockbuster, video-game key art, or generic action thriller. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	neon_noir_action = wet streets + neon + anamorphic. glamour_finance_excess = 1980s Wall Street mahogany / gold. superhero_blockbuster = comic-book key art. video_game_character = Unreal-Engine character render. generic_action_thriller = ARRI cinematic.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "neon_noir_action",
        "glamour_finance_excess",
        "superhero_blockbuster",
        "video_game_character",
        "generic_action_thriller"
      ],
      "description": "neon_noir_action = wet streets + neon + anamorphic. glamour_finance_excess = 1980s Wall Street mahogany / gold. superhero_blockbuster = comic-book key art. video_game_character = Unreal-Engine character render. generic_action_thriller = ARRI cinematic."
    }
  },
  "required": [
    "style"
  ]
}

apply_high_fashion_editorial

High-fashion magazine cover/editorial energy. Choose a photographer mood: Mario Testino glossy, Steven Klein dark cinematic, Inez & Vinoodh hard-flash, Annie Leibovitz painterly, Tim Walker dreamlike, Peter Lindbergh black-and-white natural, or Cass Bird off-duty. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	Photographer attribution drives the lighting + camera + grade stack.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "testino_glossy",
        "klein_dark_cinematic",
        "inez_vinoodh_hard_flash",
        "leibovitz_painterly",
        "walker_dreamlike",
        "lindbergh_bw_natural",
        "cass_bird_off_duty"
      ],
      "description": "Photographer attribution drives the lighting + camera + grade stack."
    }
  },
  "required": [
    "style"
  ]
}

apply_graphic_editorial_portrait

Sharp graphic editorial portrait — premium fashion-magazine grade, hard graphic composition. Classic studio or golden-hour outdoor. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	classic = Hasselblad H6D studio. golden_hour = Canon R5 outdoor.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "classic",
        "golden_hour"
      ],
      "description": "classic = Hasselblad H6D studio. golden_hour = Canon R5 outdoor."
    }
  },
  "required": [
    "style"
  ]
}

apply_travel

Luxury travel + hotel editorial. Real architecture is preserved exactly (no inventing buildings). Choose subject: hotel hero, rural property, scenic view, drone aerial, lifestyle moment, or interior. If you attach a reference image of a real property, the architecture lock kicks in automatically. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	hotel_hero = property is the star. rural_property = country estate. scenic_view = pure landscape. drone_aerial = top-down or 45° from above. lifestyle = model + destination. interior = inside the property.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "hotel_hero",
        "rural_property",
        "scenic_view",
        "drone_aerial",
        "lifestyle",
        "interior"
      ],
      "description": "hotel_hero = property is the star. rural_property = country estate. scenic_view = pure landscape. drone_aerial = top-down or 45° from above. lifestyle = model + destination. interior = inside the property."
    }
  },
  "required": [
    "style"
  ]
}

apply_wellness

Wellness / yoga / fitness / lifestyle campaign — warm amber tropical, tropical paradise cinematic, or high-key cyan beach. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	warm_amber_tropical = warm honey grade with golden haze. hanalei_cinematic = soft golden mist + infinity pool reflection. high_key_cyan_beach = bright daylit cyan ocean.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "warm_amber_tropical",
        "hanalei_cinematic",
        "high_key_cyan_beach"
      ],
      "description": "warm_amber_tropical = warm honey grade with golden haze. hanalei_cinematic = soft golden mist + infinity pool reflection. high_key_cyan_beach = bright daylit cyan ocean."
    }
  },
  "required": [
    "style"
  ]
}

apply_cinematic_anamorphic

ARRI Alexa anamorphic widescreen film look. Choose grade: warm golden, cool noir, or moody desaturated. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	warm_golden = late-afternoon honey. cool_noir = neon-fill desaturated. moody_desaturated = soft window low-contrast.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "warm_golden",
        "cool_noir",
        "moody_desaturated"
      ],
      "description": "warm_golden = late-afternoon honey. cool_noir = neon-fill desaturated. moody_desaturated = soft window low-contrast."
    }
  },
  "required": [
    "style"
  ]
}

apply_magic_hour_portrait

Golden-hour rim-light editorial portrait. Choose camera: Canon R5 + 85mm f/1.2 or Hasselblad H6D + 80mm. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	canon_85mm = Canon R5 portrait standard. hasselblad_80mm = medium-format luxury.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "canon_85mm",
        "hasselblad_80mm"
      ],
      "description": "canon_85mm = Canon R5 portrait standard. hasselblad_80mm = medium-format luxury."
    }
  },
  "required": [
    "style"
  ]
}

apply_product

Product photography. Choose: clean studio hero shot, real-world lifestyle, extreme macro detail, or top-down flat lay. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	clean_studio = seamless backdrop hero. lifestyle = product in use. macro_detail = extreme close-up texture. flat_lay = top-down catalog.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "clean_studio",
        "lifestyle",
        "macro_detail",
        "flat_lay"
      ],
      "description": "clean_studio = seamless backdrop hero. lifestyle = product in use. macro_detail = extreme close-up texture. flat_lay = top-down catalog."
    }
  },
  "required": [
    "style"
  ]
}

apply_ugc

User-generated content — looks like a real person captured it casually. Choose: phone shot, film point-and-shoot, mirror selfie, or car selfie. Returns the styled prompt stack for your shot — pair it with generate_image.

Parameters2

subject	string	optional	What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
style	string	required	phone_shot = iPhone-style snap. film_pointshoot = Contax T2 grain. mirror_selfie = bathroom/bedroom mirror. car_selfie = inside-the-car phone.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "What you want to shoot. E.g. \"a woman walking through a hotel lobby\" or \"morning coffee on the balcony\"."
    },
    "style": {
      "type": "string",
      "enum": [
        "phone_shot",
        "film_pointshoot",
        "mirror_selfie",
        "car_selfie"
      ],
      "description": "phone_shot = iPhone-style snap. film_pointshoot = Contax T2 grain. mirror_selfie = bathroom/bedroom mirror. car_selfie = inside-the-car phone."
    }
  },
  "required": [
    "style"
  ]
}

generate_image

Generate one or more Switch images. Auto-routes to the right model based on subject (Nano Banana 2 default, GPT Image 2 for swimwear/beach, Switch Model/Ultra/Pro for sexier content, Nano Banana Pro for typography-heavy). 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.

Parameters9

subject	string	required	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".
count	integer	optional	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.
style	string	optional	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".
aspect_ratio	string	optional	Image aspect ratio. Default 9:16 (vertical, social-friendly).
real_photo_look	boolean	optional	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.
model	string	optional	Optional explicit model. If omitted, auto-routed based on subject content (see tool description).
reference_image_urls	array	optional	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.
face_reference_ids	array	optional	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.
folder_name	string	optional	Optional Switch Studio folder name. Auto-created if missing. Defaults to the chat-derived title.

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "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\"."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "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."
    },
    "style": {
      "type": "string",
      "enum": [
        "iphone_realism/digital_phone",
        "iphone_realism/film_pointshoot",
        "iphone_realism/off_duty_intimate",
        "movie_scene/neon_noir_action",
        "movie_scene/glamour_finance_excess",
        "movie_scene/superhero_blockbuster",
        "movie_scene/video_game_character",
        "movie_scene/generic_action_thriller",
        "high_fashion_editorial/testino_glossy",
        "high_fashion_editorial/klein_dark_cinematic",
        "high_fashion_editorial/inez_vinoodh_hard_flash",
        "high_fashion_editorial/leibovitz_painterly",
        "high_fashion_editorial/walker_dreamlike",
        "high_fashion_editorial/lindbergh_bw_natural",
        "high_fashion_editorial/cass_bird_off_duty",
        "graphic_editorial_portrait/classic",
        "graphic_editorial_portrait/golden_hour",
        "travel/hotel_hero",
        "travel/rural_property",
        "travel/scenic_view",
        "travel/drone_aerial",
        "travel/lifestyle",
        "travel/interior",
        "wellness/warm_amber_tropical",
        "wellness/hanalei_cinematic",
        "wellness/high_key_cyan_beach",
        "cinematic_anamorphic/warm_golden",
        "cinematic_anamorphic/cool_noir",
        "cinematic_anamorphic/moody_desaturated",
        "magic_hour_portrait/canon_85mm",
        "magic_hour_portrait/hasselblad_80mm",
        "product/clean_studio",
        "product/lifestyle",
        "product/macro_detail",
        "product/flat_lay",
        "ugc/phone_shot",
        "ugc/film_pointshoot",
        "ugc/mirror_selfie",
        "ugc/car_selfie"
      ],
      "description": "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\"."
    },
    "aspect_ratio": {
      "type": "string",
      "enum": [
        "9:16",
        "16:9",
        "1:1",
        "4:5",
        "5:4",
        "3:2",
        "2:3",
        "4:3"
      ],
      "description": "Image aspect ratio. Default 9:16 (vertical, social-friendly)."
    },
    "real_photo_look": {
      "type": "boolean",
      "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."
    },
    "model": {
      "type": "string",
      "enum": [
        "Nano Banana 2",
        "Nano Banana Pro",
        "Switch Model",
        "Switch Pro",
        "Switch Ultra",
        "GPT Image 2",
        "WAN 2.7"
      ],
      "description": "Optional explicit model. If omitted, auto-routed based on subject content (see tool description)."
    },
    "reference_image_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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."
    },
    "face_reference_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "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."
    },
    "folder_name": {
      "type": "string",
      "description": "Optional Switch Studio folder name. Auto-created if missing. Defaults to the chat-derived title."
    }
  },
  "required": [
    "subject"
  ]
}

cancel_my_task

Stop one of your generation tasks by task id — works on queued AND running tasks. Already-saved images stay in your library; nothing is deleted or refunded. Returns how many images were saved out of how many you requested.

Parameters1

taskId

string

required

Task id from generate_image or list_my_tasks.

Raw schema

{
  "type": "object",
  "properties": {
    "taskId": {
      "type": "string",
      "description": "Task id from generate_image or list_my_tasks."
    }
  },
  "required": [
    "taskId"
  ]
}

generate_video

Generate Switch video across the real provider lineup (Kling, Seedance, Switch Video/WAN 2.7, Switch Video Edit, Topaz upscale) and modes (text-to-video, image-to-video, frame-to-frame, motion, omni, reference-to-video, video-edit, upscale). ALWAYS call list_video_models first to pick the right model + mode and see its required inputs. Pass one shot, or shots:[...] for a storyboard (max 4 by default, hard max 10) where EACH shot is DIFFERENT — never repeat one prompt to get copies. Renders async (~30-90s); a background job delivers each clip to your library. Returns a task_id per shot — poll get_video_status or list_my_videos.

Parameters17

subject	string	optional	The shot: subject + motion + scene (video needs motion language, e.g. "slow push-in").
model	string	optional	Model id from list_video_models (e.g. kling-v3, seedance-2.0-t2v, wan-2.7-t2v, topaz). Or prefer option_id from list_video_models.
mode	string	optional	Video mode. Must be supported by the chosen model (see list_video_models).
character_orientation	string	optional	Motion mode only: follow the character image (default) or the reference video.
option_id	string	optional	Optional catalog id from list_video_models (e.g. "kling-image"); use instead of model+mode.
image_url	string	optional	Required for image-to-video / frame-to-frame / motion. Accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media) OR a public https url. An asset id is resolved server-side, so just pass the id you have — no need to fetch a url first.
end_image_url	string	optional	End frame for frame-to-frame mode.
video_url	string	optional	Required for video-edit and upscale (the source clip). Must be a publicly downloadable https URL.
reference_image_urls	array	optional	GENERIC reference images (products, scenery, outfits, style). Each entry accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media / get_my_active_references) OR a public https url — asset ids are resolved server-side. Seedance reference/omni accepts up to 9; Kling Omni up to 7. For Seedance, at least one image or video reference is required. For a person's face/likeness use face_reference_ids instead.
face_reference_ids	array	optional	Face reference asset ids from upload_reference_asset (frame_type "face") — the ONLY way to use a face/likeness reference in video. Each id is verified server-side (your own untouched original + identity verification) before the shot fires or is charged; URLs and generic uploads here are rejected.
reference_video_urls	array	optional	Seedance reference/omni only: up to 3 reference video clips for motion/style guidance. A Seedance video ref can satisfy the required visual anchor. NOTE: the AUDIO track of these clips is IGNORED — never extracted or preserved.
reference_audio_urls	array	optional	Seedance reference/omni only: up to 3 reference audio files to drive synthesized audio. Requires at least one reference image or video.
audio	boolean	optional	Omni / Seedance refs: generate audio. Omni is ON by default; set false for a silent clip. Other models ignore this. See list_video_models for which models generate audio and the max seconds with vs without audio.
duration	string	optional	Clip length in seconds. Default 5. Seedance does 4-15s; Switch Video (WAN) does 5/10/15; Kling/Switch Video Edit cap at 10 — see each model's durations in list_video_models.
aspect_ratio	string	optional	e.g. 9:16, 16:9, 1:1. Must be allowed for the model (see list_video_models).
resolution	string	optional	Output resolution. Defaults to 1080p where the model supports it. 720p is cheaper and faster. 480p is the cheapest, only on Seedance 2.0 Mini (budget tier). 4K is only on Kling v3 text/image and Kling Omni; Seedance text-to-video is 720p only. Each model lists its available resolutions in list_video_models.
shots	array	optional	A storyboard of 1-10 DISTINCT shots. Each item takes the same fields as a single shot (subject, model, mode, image_url, etc.).

Raw schema

{
  "type": "object",
  "properties": {
    "subject": {
      "type": "string",
      "description": "The shot: subject + motion + scene (video needs motion language, e.g. \"slow push-in\")."
    },
    "model": {
      "type": "string",
      "description": "Model id from list_video_models (e.g. kling-v3, seedance-2.0-t2v, wan-2.7-t2v, topaz). Or prefer option_id from list_video_models."
    },
    "mode": {
      "type": "string",
      "enum": [
        "text-to-video",
        "image-to-video",
        "reference-to-video",
        "frame-to-frame",
        "motion",
        "omni",
        "video-edit",
        "upscale"
      ],
      "description": "Video mode. Must be supported by the chosen model (see list_video_models)."
    },
    "character_orientation": {
      "type": "string",
      "enum": [
        "image",
        "video"
      ],
      "description": "Motion mode only: follow the character image (default) or the reference video."
    },
    "option_id": {
      "type": "string",
      "description": "Optional catalog id from list_video_models (e.g. \"kling-image\"); use instead of model+mode."
    },
    "image_url": {
      "type": "string",
      "description": "Required for image-to-video / frame-to-frame / motion. Accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media) OR a public https url. An asset id is resolved server-side, so just pass the id you have — no need to fetch a url first."
    },
    "end_image_url": {
      "type": "string",
      "description": "End frame for frame-to-frame mode."
    },
    "video_url": {
      "type": "string",
      "description": "Required for video-edit and upscale (the source clip). Must be a publicly downloadable https URL."
    },
    "reference_image_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "GENERIC reference images (products, scenery, outfits, style). Each entry accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media / get_my_active_references) OR a public https url — asset ids are resolved server-side. Seedance reference/omni accepts up to 9; Kling Omni up to 7. For Seedance, at least one image or video reference is required. For a person's face/likeness use face_reference_ids instead."
    },
    "face_reference_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Face reference asset ids from upload_reference_asset (frame_type \"face\") — the ONLY way to use a face/likeness reference in video. Each id is verified server-side (your own untouched original + identity verification) before the shot fires or is charged; URLs and generic uploads here are rejected."
    },
    "reference_video_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Seedance reference/omni only: up to 3 reference video clips for motion/style guidance. A Seedance video ref can satisfy the required visual anchor. NOTE: the AUDIO track of these clips is IGNORED — never extracted or preserved."
    },
    "reference_audio_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Seedance reference/omni only: up to 3 reference audio files to drive synthesized audio. Requires at least one reference image or video."
    },
    "audio": {
      "type": "boolean",
      "description": "Omni / Seedance refs: generate audio. Omni is ON by default; set false for a silent clip. Other models ignore this. See list_video_models for which models generate audio and the max seconds with vs without audio."
    },
    "duration": {
      "type": "string",
      "description": "Clip length in seconds. Default 5. Seedance does 4-15s; Switch Video (WAN) does 5/10/15; Kling/Switch Video Edit cap at 10 — see each model's durations in list_video_models."
    },
    "aspect_ratio": {
      "type": "string",
      "description": "e.g. 9:16, 16:9, 1:1. Must be allowed for the model (see list_video_models)."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ],
      "description": "Output resolution. Defaults to 1080p where the model supports it. 720p is cheaper and faster. 480p is the cheapest, only on Seedance 2.0 Mini (budget tier). 4K is only on Kling v3 text/image and Kling Omni; Seedance text-to-video is 720p only. Each model lists its available resolutions in list_video_models."
    },
    "shots": {
      "type": "array",
      "description": "A storyboard of 1-10 DISTINCT shots. Each item takes the same fields as a single shot (subject, model, mode, image_url, etc.).",
      "items": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "description": "The shot: subject + motion + scene (video needs motion language, e.g. \"slow push-in\")."
          },
          "model": {
            "type": "string",
            "description": "Model id from list_video_models (e.g. kling-v3, seedance-2.0-t2v, wan-2.7-t2v, topaz). Or prefer option_id from list_video_models."
          },
          "mode": {
            "type": "string",
            "enum": [
              "text-to-video",
              "image-to-video",
              "reference-to-video",
              "frame-to-frame",
              "motion",
              "omni",
              "video-edit",
              "upscale"
            ],
            "description": "Video mode. Must be supported by the chosen model (see list_video_models)."
          },
          "character_orientation": {
            "type": "string",
            "enum": [
              "image",
              "video"
            ],
            "description": "Motion mode only: follow the character image (default) or the reference video."
          },
          "option_id": {
            "type": "string",
            "description": "Optional catalog id from list_video_models (e.g. \"kling-image\"); use instead of model+mode."
          },
          "image_url": {
            "type": "string",
            "description": "Required for image-to-video / frame-to-frame / motion. Accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media) OR a public https url. An asset id is resolved server-side, so just pass the id you have — no need to fetch a url first."
          },
          "end_image_url": {
            "type": "string",
            "description": "End frame for frame-to-frame mode."
          },
          "video_url": {
            "type": "string",
            "description": "Required for video-edit and upscale (the source clip). Must be a publicly downloadable https URL."
          },
          "reference_image_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "GENERIC reference images (products, scenery, outfits, style). Each entry accepts EITHER a Switch asset id (from show_media / list_my_assets / upload_media / get_my_active_references) OR a public https url — asset ids are resolved server-side. Seedance reference/omni accepts up to 9; Kling Omni up to 7. For Seedance, at least one image or video reference is required. For a person's face/likeness use face_reference_ids instead."
          },
          "face_reference_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Face reference asset ids from upload_reference_asset (frame_type \"face\") — the ONLY way to use a face/likeness reference in video. Each id is verified server-side (your own untouched original + identity verification) before the shot fires or is charged; URLs and generic uploads here are rejected."
          },
          "reference_video_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Seedance reference/omni only: up to 3 reference video clips for motion/style guidance. A Seedance video ref can satisfy the required visual anchor. NOTE: the AUDIO track of these clips is IGNORED — never extracted or preserved."
          },
          "reference_audio_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Seedance reference/omni only: up to 3 reference audio files to drive synthesized audio. Requires at least one reference image or video."
          },
          "audio": {
            "type": "boolean",
            "description": "Omni / Seedance refs: generate audio. Omni is ON by default; set false for a silent clip. Other models ignore this. See list_video_models for which models generate audio and the max seconds with vs without audio."
          },
          "duration": {
            "type": "string",
            "description": "Clip length in seconds. Default 5. Seedance does 4-15s; Switch Video (WAN) does 5/10/15; Kling/Switch Video Edit cap at 10 — see each model's durations in list_video_models."
          },
          "aspect_ratio": {
            "type": "string",
            "description": "e.g. 9:16, 16:9, 1:1. Must be allowed for the model (see list_video_models)."
          },
          "resolution": {
            "type": "string",
            "enum": [
              "480p",
              "720p",
              "1080p",
              "4k"
            ],
            "description": "Output resolution. Defaults to 1080p where the model supports it. 720p is cheaper and faster. 480p is the cheapest, only on Seedance 2.0 Mini (budget tier). 4K is only on Kling v3 text/image and Kling Omni; Seedance text-to-video is 720p only. Each model lists its available resolutions in list_video_models."
          }
        }
      }
    }
  }
}

list_video_models

List the video providers, models, and modes available to your Switch account, with each model's required inputs, allowed aspect ratios and durations, and a rough per-second cost. Call this before generate_video so you pick a real model + mode and supply the right inputs.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

get_video_status

Check the status of one of your video jobs by task_id (from generate_video) or job_id. Returns status, a viewable view_url when finished, or the error if it failed. Poll this every ~20s — do not loop rapidly.

Parameters2

task_id	string	optional	Task id returned by generate_video.
job_id	string	optional	Alternatively, the job_id.

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "description": "Task id returned by generate_video."
    },
    "job_id": {
      "type": "string",
      "description": "Alternatively, the job_id."
    }
  }
}

list_my_videos

List your recent Switch videos, newest first — id, status, prompt, model, and a viewable view_url for finished clips. Use this to check whether videos finished and to let the user choose which one they want.

Parameters2

count	integer	optional	How many to return. Default 10. Max 50.
status	string	optional	Optional filter: submitted, processing, succeed, failed, or all.

Raw schema

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "description": "How many to return. Default 10. Max 50."
    },
    "status": {
      "type": "string",
      "description": "Optional filter: submitted, processing, succeed, failed, or all."
    }
  }
}

lip_sync_video

Lip-sync audio onto one of your videos. RECOMMENDED: action="create" with engine="best" + video_url + sound_file (base64 data URI) — syncs the whole clip on the highest-quality engine, no face step needed. Kling flow (manual timing control): (1) action="identify-face" with video_url (MP4/MOV, 2-60s, <=100MB, 720p/1080p); (2) action="create" with session_id + face_id + audio + timing IN MILLISECONDS (sound_start_time, sound_end_time, sound_insert_time) + optional speech_volume/original_audio_volume (0-100); (3) action="status" with the task_id to poll — returns a branded SwitchApp view_url when done. Charges credits on create; failed jobs are refunded.

Parameters13

action	string	required	Which step to run.
engine	string	optional	create: "best" = highest-quality whole-clip sync (needs only video_url + sound_file). Default "kling" (timeline flow).
video_url	string	optional	identify-face: the source video (MP4/MOV, 2-60s, <=100MB, 720p/1080p). Use a SwitchApp/public URL.
session_id	string	optional	create: from identify-face.
face_id	string	optional	create: a face_id from identify-face (one face supported).
sound_file	string	optional	create: base64 data URI of the audio (e.g. data:audio/mpeg;base64,...).
audio_id	string	optional	create: alternative to sound_file — an existing audio id.
sound_start_time	integer	optional	create: audio start, in MILLISECONDS.
sound_end_time	integer	optional	create: audio end, in MILLISECONDS.
sound_insert_time	integer	optional	create: where in the video to place the audio, in MILLISECONDS.
speech_volume	number	optional	create: how loud the new speech is, as a percent 0-100 (default 100).
original_audio_volume	number	optional	create: how loud the clip's own sound stays, as a percent 0-100 (default 0).
task_id	string	optional	status: the task_id from create.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "identify-face",
        "create",
        "status"
      ],
      "description": "Which step to run."
    },
    "engine": {
      "type": "string",
      "enum": [
        "best",
        "kling"
      ],
      "description": "create: \"best\" = highest-quality whole-clip sync (needs only video_url + sound_file). Default \"kling\" (timeline flow)."
    },
    "video_url": {
      "type": "string",
      "description": "identify-face: the source video (MP4/MOV, 2-60s, <=100MB, 720p/1080p). Use a SwitchApp/public URL."
    },
    "session_id": {
      "type": "string",
      "description": "create: from identify-face."
    },
    "face_id": {
      "type": "string",
      "description": "create: a face_id from identify-face (one face supported)."
    },
    "sound_file": {
      "type": "string",
      "description": "create: base64 data URI of the audio (e.g. data:audio/mpeg;base64,...)."
    },
    "audio_id": {
      "type": "string",
      "description": "create: alternative to sound_file — an existing audio id."
    },
    "sound_start_time": {
      "type": "integer",
      "description": "create: audio start, in MILLISECONDS."
    },
    "sound_end_time": {
      "type": "integer",
      "description": "create: audio end, in MILLISECONDS."
    },
    "sound_insert_time": {
      "type": "integer",
      "description": "create: where in the video to place the audio, in MILLISECONDS."
    },
    "speech_volume": {
      "type": "number",
      "description": "create: how loud the new speech is, as a percent 0-100 (default 100)."
    },
    "original_audio_volume": {
      "type": "number",
      "description": "create: how loud the clip's own sound stays, as a percent 0-100 (default 0)."
    },
    "task_id": {
      "type": "string",
      "description": "status: the task_id from create."
    }
  },
  "required": [
    "action"
  ]
}

talking_avatar_video

Turn a face photo into a lip-synced talking-head video that speaks your text (or your audio). Provide image_url (a clear face photo) and either script (text to speak, max 2500 characters) or audio_url. Optional voice_id / language / voice_settings. Renders in ~1-5 minutes (single call, returns the finished branded video) and is saved to your library. Charged per video.

Parameters6

image_url	string	required	A clear face photo (Switch/public URL). Required.
script	string	optional	Text the avatar speaks. Max 2500 characters. Required unless audio_url is given.
audio_url	string	optional	Pre-recorded audio URL to lip-sync instead of generating speech from script.
voice_id	string	optional	Optional voice id (from clone_voice / your library).
language	string	optional	Optional language code (default en).
voice_settings	object	optional	Optional: { stability, similarityBoost, style, useSpeakerBoost } 0-1.

Raw schema

{
  "type": "object",
  "properties": {
    "image_url": {
      "type": "string",
      "description": "A clear face photo (Switch/public URL). Required."
    },
    "script": {
      "type": "string",
      "description": "Text the avatar speaks. Max 2500 characters. Required unless audio_url is given."
    },
    "audio_url": {
      "type": "string",
      "description": "Pre-recorded audio URL to lip-sync instead of generating speech from script."
    },
    "voice_id": {
      "type": "string",
      "description": "Optional voice id (from clone_voice / your library)."
    },
    "language": {
      "type": "string",
      "description": "Optional language code (default en)."
    },
    "voice_settings": {
      "type": "object",
      "description": "Optional: { stability, similarityBoost, style, useSpeakerBoost } 0-1."
    }
  },
  "required": [
    "image_url"
  ]
}

voice

Your saved voices — one tool for the whole voice library. Users speak plain language and never know ids: resolve every voice by NAME yourself (call action "list" first if unsure) and never ask the user for an id. action="list" returns every saved voice with voice_id, name, kind and ready — kind "reference" is an instant voice match saved from a clip and kind "clone" is a trained voice (both speak through generate_audio: pass the NAME as its voice param); kind "avatar" voices drive talking_avatar_video. action="create" saves a NEW reference voice from a clip: voice_name plus audio_url (e.g. the url upload_media returned) or audio_base64 (+ format) — free, ready instantly. action="rename" renames a saved voice (voice_id takes the id OR the current name, new_name is the new name). action="clone" registers a voice for talking_avatar_video from audio_sample_url + voice_name (charged 2 credits). action="delete" removes a voice by voice_id or name.

Parameters8

action	string	required	Which operation to run.
voice_name	string	optional	create/clone: what to call the voice (unique per account).
audio_url	string	optional	create: URL of a 10-30 second clip of the voice — e.g. the url returned by upload_media.
audio_base64	string	optional	create: the clip as base64 when there is no URL.
format	string	optional	create: clip format when sending audio_base64. Default wav.
audio_sample_url	string	optional	clone: a 10-30 second voice sample URL (reachable).
voice_id	string	optional	delete/rename: the voice id OR its name — names are resolved for you.
new_name	string	optional	rename: the new name for the voice.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "clone",
        "list",
        "delete",
        "create",
        "rename"
      ],
      "description": "Which operation to run."
    },
    "voice_name": {
      "type": "string",
      "description": "create/clone: what to call the voice (unique per account)."
    },
    "audio_url": {
      "type": "string",
      "description": "create: URL of a 10-30 second clip of the voice — e.g. the url returned by upload_media."
    },
    "audio_base64": {
      "type": "string",
      "description": "create: the clip as base64 when there is no URL."
    },
    "format": {
      "type": "string",
      "enum": [
        "wav",
        "mp3",
        "ogg",
        "m4a",
        "aac"
      ],
      "description": "create: clip format when sending audio_base64. Default wav."
    },
    "audio_sample_url": {
      "type": "string",
      "description": "clone: a 10-30 second voice sample URL (reachable)."
    },
    "voice_id": {
      "type": "string",
      "description": "delete/rename: the voice id OR its name — names are resolved for you."
    },
    "new_name": {
      "type": "string",
      "description": "rename: the new name for the voice."
    }
  },
  "required": [
    "action"
  ]
}

generate_audio

Generate spoken audio from text: narration, a voiceover, a read-aloud script, or a multi-voice dialogue. Pass text (up to 2048 chars) — the words to be spoken. To speak in one of YOUR saved voices, pass voice with the voice NAME (or id): users speak plain language and never know ids, so resolve the name yourself (the voice tool, action "list", shows every saved voice) and never ask the user for an id. Reference voices, trained clones and preset voices are all routed correctly by kind. To match a voice instantly from a clip instead, pass reference_audio_url (a short clip) or up to 3 reference_audio_urls and address them as @Audio1, @Audio2, @Audio3 in the text for dialogue. Alternatively pass image_url to voice a scene from a picture (cannot combine with reference audio). Optional speech_rate (-50..100), pitch (-12..12), loudness (-50..100). Returns a playable audio_url, duration_seconds, and generation_id (also saved to your library).

Parameters9

text	string	required	The words to speak / narrate / perform. Max 2048 chars. For dialogue, address voices as @Audio1, @Audio2, @Audio3.
voice	string	optional	Optional. A saved voice — pass its NAME (or id); it is resolved and routed by kind automatically. Omit for a natural default voice.
reference_audio_url	string	optional	Optional. A short clip URL to instantly match that voice.
reference_audio_urls	array	optional	Optional. Up to 3 reference clip URLs for multi-voice dialogue.
image_url	string	optional	Optional. Voice a scene from a picture. Cannot be combined with reference audio.
speech_rate	number	optional	Optional. Speaking speed, -50 (slower) to 100 (faster). 0 is normal.
pitch	number	optional	Optional. Pitch, -12 to 12. 0 is normal.
loudness	number	optional	Optional. Loudness, -50 (quieter) to 100 (louder). 0 is normal.
format	string	optional	Optional output format. Default mp3.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "The words to speak / narrate / perform. Max 2048 chars. For dialogue, address voices as @Audio1, @Audio2, @Audio3."
    },
    "voice": {
      "type": "string",
      "description": "Optional. A saved voice — pass its NAME (or id); it is resolved and routed by kind automatically. Omit for a natural default voice."
    },
    "reference_audio_url": {
      "type": "string",
      "description": "Optional. A short clip URL to instantly match that voice."
    },
    "reference_audio_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. Up to 3 reference clip URLs for multi-voice dialogue."
    },
    "image_url": {
      "type": "string",
      "description": "Optional. Voice a scene from a picture. Cannot be combined with reference audio."
    },
    "speech_rate": {
      "type": "number",
      "description": "Optional. Speaking speed, -50 (slower) to 100 (faster). 0 is normal."
    },
    "pitch": {
      "type": "number",
      "description": "Optional. Pitch, -12 to 12. 0 is normal."
    },
    "loudness": {
      "type": "number",
      "description": "Optional. Loudness, -50 (quieter) to 100 (louder). 0 is normal."
    },
    "format": {
      "type": "string",
      "enum": [
        "mp3",
        "wav",
        "ogg_opus"
      ],
      "description": "Optional output format. Default mp3."
    }
  },
  "required": [
    "text"
  ]
}

upload_reference_asset

Upload an image, video, or audio reference into Switch cloud and get a ready-to-use reference URL. Pass kind=image|video|audio. Returns reference_image_urls / reference_video_urls / reference_audio_urls for generate_image and generate_video. Image and video references are also added to your active Studio reference strip (the same one your desktop uses) unless activate=false. PREFERRED for real files: call with presign=true to get an upload_url, PUT the bytes straight to it (no base64 through the model), then call again with confirm_path to verify and add it — works for image, video, and audio. base64/url is only for tiny inline files.

Parameters9

kind	string	required	Reference type to upload.
url	string	optional	Public https URL to fetch server-side.
base64	string	optional	Base64 bytes (optionally a data: URL). Best for small files; large video should use presign.
mime	string	optional	MIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac.
filename	string	optional	Optional source filename for extension/display.
activate	boolean	optional	Image/video: add to the active Studio reference strip. Default true. Audio never touches the strip.
frame_type	string	optional	Image strip label: ref (default), face, body, clothes, scenery, product, typography. Use "face" for a person's face/likeness — face uploads are stored as untouched originals in the private reference bucket and their returned asset_id is the ONLY handle face-capable generation accepts (KYC-verified accounts only).
presign	boolean	optional	Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled.
confirm_path	string	optional	The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip.

Raw schema

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "image",
        "video",
        "audio"
      ],
      "description": "Reference type to upload."
    },
    "url": {
      "type": "string",
      "description": "Public https URL to fetch server-side."
    },
    "base64": {
      "type": "string",
      "description": "Base64 bytes (optionally a data: URL). Best for small files; large video should use presign."
    },
    "mime": {
      "type": "string",
      "description": "MIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac."
    },
    "filename": {
      "type": "string",
      "description": "Optional source filename for extension/display."
    },
    "activate": {
      "type": "boolean",
      "description": "Image/video: add to the active Studio reference strip. Default true. Audio never touches the strip."
    },
    "frame_type": {
      "type": "string",
      "description": "Image strip label: ref (default), face, body, clothes, scenery, product, typography. Use \"face\" for a person's face/likeness — face uploads are stored as untouched originals in the private reference bucket and their returned asset_id is the ONLY handle face-capable generation accepts (KYC-verified accounts only)."
    },
    "presign": {
      "type": "boolean",
      "description": "Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled."
    },
    "confirm_path": {
      "type": "string",
      "description": "The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip."
    }
  },
  "required": [
    "kind"
  ]
}

stitch_videos

Stitch several of your Switch videos together into ONE video, played back-to-back in the order you give. Pass clip_asset_ids: an ORDERED list of your video ids (get them from list_my_videos) — the first id plays first. Optional orientation (landscape|portrait|square), fps, quality. Renders the combined video with ffmpeg and returns the finished, downloadable video url right away (also saved to list_my_videos). Use this whenever the user wants to combine, join, merge, or concatenate multiple clips into one.

Parameters5

clip_asset_ids	array	required	Ordered list of your video ids (from list_my_videos). At least 2. Output order = this order.
orientation	string	optional	landscape (1920x1080, default), portrait (1080x1920), or square (1080x1080).
fps	integer	optional	Frames per second. Default 30.
quality	string	optional	draft, standard (default), or high.
project_name	string	optional	Optional name for the output video.

Raw schema

{
  "type": "object",
  "properties": {
    "clip_asset_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ordered list of your video ids (from list_my_videos). At least 2. Output order = this order."
    },
    "orientation": {
      "type": "string",
      "description": "landscape (1920x1080, default), portrait (1080x1920), or square (1080x1080)."
    },
    "fps": {
      "type": "integer",
      "description": "Frames per second. Default 30."
    },
    "quality": {
      "type": "string",
      "description": "draft, standard (default), or high."
    },
    "project_name": {
      "type": "string",
      "description": "Optional name for the output video."
    }
  },
  "required": [
    "clip_asset_ids"
  ]
}

analyze_video

Switch Vision — watch and understand a video (or image) like a human and answer a question about it: scenes, subjects, actions, on-screen text, pacing, mood and sentiment. Pass video_url (a public https video URL, including YouTube) OR one of your own Switch videos (a video/asset id from list_my_videos / list_my_assets / upload_media). Add an optional question to focus the analysis (e.g. "what is the tone and energy?", "list the cuts and what each shot shows"). Use this whenever the user gives you a reference video and wants its style, energy, structure or content understood — for example before making a new video that matches it.

Parameters2

video_url	string	required	A public https video URL (YouTube ok), OR one of your own Switch video/asset ids.
question	string	optional	Optional. What to find out about the video — tone, structure, on-screen text, sentiment, etc.

Raw schema

{
  "type": "object",
  "properties": {
    "video_url": {
      "type": "string",
      "description": "A public https video URL (YouTube ok), OR one of your own Switch video/asset ids."
    },
    "question": {
      "type": "string",
      "description": "Optional. What to find out about the video — tone, structure, on-screen text, sentiment, etc."
    }
  },
  "required": [
    "video_url"
  ]
}

create_depth_map

Turn a video into a DEPTH MAP: a grayscale video where brightness encodes distance, used as a motion reference so a new generated subject moves exactly like your source clip. Pass video_url (a public https video URL) OR one of your own Switch video ids (from list_my_videos or list_my_assets). For an external URL also pass duration_seconds (the clip length; your own Switch videos carry it automatically) because the render is billed per second of video. Returns a task_id right away; poll get_depth_map_status until the download URL is ready (usually a few minutes). If the render fails, your tokens are returned automatically.

Parameters2

video_url	string	required	A public https video URL, OR one of your own Switch video ids.
duration_seconds	number	optional	Clip length in seconds. Required for external URLs; your own Switch videos are measured automatically.

Raw schema

{
  "type": "object",
  "properties": {
    "video_url": {
      "type": "string",
      "description": "A public https video URL, OR one of your own Switch video ids."
    },
    "duration_seconds": {
      "type": "number",
      "description": "Clip length in seconds. Required for external URLs; your own Switch videos are measured automatically."
    }
  },
  "required": [
    "video_url"
  ]
}

get_depth_map_status

Check one of your depth map renders started with create_depth_map. Pass the task_id it returned. While rendering it reports processing; when finished it returns depth_video_url, a download link for the grayscale motion reference video. If the render failed, it says so and confirms your tokens were returned.

Parameters1

task_id

string

required

The task_id returned by create_depth_map.

Raw schema

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "description": "The task_id returned by create_depth_map."
    }
  },
  "required": [
    "task_id"
  ]
}

analyze_video_report

Run the FULL Switch Vision analysis on a video, the same premium report the Video Analysis page produces: it watches AND listens in three forensic passes and returns a structured report with every category: overview (scores and takeaways), a second by second timeline, audio, visual craft, story and retention, speech transcript, ready to run recreation prompts, and metadata. Pass video_url (a public https video URL, YouTube included) OR one of your own Switch video ids. For an external file also pass duration_seconds (YouTube and your own videos are measured automatically) because the analysis is billed per second. Optional question focuses the analysis. Returns a report_id right away; poll get_vision_report until status is succeeded (a few minutes). If it cannot finish, your tokens are returned automatically. For one quick question about a video use analyze_video instead; this tool is the full paid report.

Parameters3

video_url	string	required	A public https video URL (YouTube ok), OR one of your own Switch video ids.
duration_seconds	number	optional	Length in seconds. Required for external files; YouTube and your own Switch videos are measured automatically.
question	string	optional	Optional. Something to pay special attention to.

Raw schema

{
  "type": "object",
  "properties": {
    "video_url": {
      "type": "string",
      "description": "A public https video URL (YouTube ok), OR one of your own Switch video ids."
    },
    "duration_seconds": {
      "type": "number",
      "description": "Length in seconds. Required for external files; YouTube and your own Switch videos are measured automatically."
    },
    "question": {
      "type": "string",
      "description": "Optional. Something to pay special attention to."
    }
  },
  "required": [
    "video_url"
  ]
}

get_vision_report

Fetch one of your finished Video Analysis reports by report_id (from analyze_video_report or list_vision_reports). Returns the complete structured report: overview scores and takeaways, the timeline of scenes, audio, visual, story, speech, the recreation section with every master prompt, and metadata, plus recreation_prompt (the ready to run prompt) at the top level. While an analysis is still running this reports processing; poll it every 20 to 30 seconds.

Parameters1

report_id

string

required

The report id to fetch.

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "description": "The report id to fetch."
    }
  },
  "required": [
    "report_id"
  ]
}

list_vision_reports

List your Video Analysis history, newest first: report_id, date, status, source kind, duration, engine, tokens charged, and each report's headline. Use it to find a past analysis, then pass its report_id to get_vision_report (full report) or video_to_prompt (just the recreation prompt).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

video_to_prompt

Turn one of your finished Video Analysis reports into ONE reusable generation prompt that recreates the source video's look, energy, pacing and mood, with a {your photo} placeholder where your own subject goes. Pass report_id (from analyze_video_report or list_vision_reports) or video_url (the exact source URL you already analyzed). Free: it rewrites the analysis you already paid for and never charges. If the video has not been analyzed yet, run analyze_video_report first. Optional focus: pass mode to control what the prompt describes, and engine to pick the model format — also free.

Parameters4

report_id	string	optional	A finished report id from analyze_video_report or list_vision_reports.
video_url	string	optional	Alternative: the exact public https URL you already analyzed.
mode	string	optional	What the prompt focuses on. action = motion/gestures only, no appearance or scene. scene = setting/camera/lighting only, no subject. action_scene = both, no appearance. description_scene (default) = full prompt including the subject's appearance.
engine	string	optional	Which model format to return: seedance (default, control-format), kling (cinematic prose), or gemini (plain paragraph for Omni).

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "description": "A finished report id from analyze_video_report or list_vision_reports."
    },
    "video_url": {
      "type": "string",
      "description": "Alternative: the exact public https URL you already analyzed."
    },
    "mode": {
      "type": "string",
      "enum": [
        "action",
        "scene",
        "action_scene",
        "description_scene"
      ],
      "description": "What the prompt focuses on. action = motion/gestures only, no appearance or scene. scene = setting/camera/lighting only, no subject. action_scene = both, no appearance. description_scene (default) = full prompt including the subject's appearance."
    },
    "engine": {
      "type": "string",
      "enum": [
        "seedance",
        "kling",
        "gemini"
      ],
      "description": "Which model format to return: seedance (default, control-format), kling (cinematic prose), or gemini (plain paragraph for Omni)."
    }
  }
}

upload_media

Upload one image into your Switch library in a single call. Pass `url` (any public https) OR `base64` + `mime`. Switch fetches/decodes it server-side, stores it, and returns a clean public URL plus the new asset id. This is THE way to use a photo the user attached in chat as a reference: pass the returned `url` directly into generate_image's reference_image_urls, OR into generate_video's image_url (image-to-video) or reference_image_urls (reference / omni video). The returned URL is provider-fetchable as-is — no presigned PUT, no curl, no confirm-upload step. Do NOT call get_my_active_references for a chat-attached photo; that strip only holds Studio-managed refs.

Parameters3

url	string	optional	Any public https URL — Switch fetches it server-side.
base64	string	optional	Base64-encoded image bytes (use this when there is no public URL).
mime	string	optional	MIME type when sending base64. Default image/png.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Any public https URL — Switch fetches it server-side."
    },
    "base64": {
      "type": "string",
      "description": "Base64-encoded image bytes (use this when there is no public URL)."
    },
    "mime": {
      "type": "string",
      "description": "MIME type when sending base64. Default image/png."
    }
  }
}

Install

Tools (40)

explore_modelscheck_balancelist_generationsshow_generationcheck_job_statusshow_medialist_my_folderslist_my_assets

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.switchapp.ai/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "switch": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.switchapp.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

MCP Server: ai.switchapp/switch

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

explore_models

check_balance

list_generations

show_generation

check_job_status

show_media

list_my_folders

list_my_assets

search_my_library

get_my_active_references

apply_iphone_realism

apply_movie_scene

apply_high_fashion_editorial

apply_graphic_editorial_portrait

apply_travel

apply_wellness

apply_cinematic_anamorphic

apply_magic_hour_portrait

apply_product

apply_ugc

generate_image

cancel_my_task

generate_video

list_video_models

get_video_status

list_my_videos

lip_sync_video

talking_avatar_video

voice

generate_audio

upload_reference_asset

stitch_videos

analyze_video

create_depth_map

get_depth_map_status

analyze_video_report

get_vision_report

list_vision_reports

video_to_prompt

upload_media

Install

Remote endpoint

Related servers