ai.switchapp/switch

Official32 tools

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

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

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.

No parameters.

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.

Parameters (1)

estimatedCostnumber
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.

Parameters (2)

statusany
"all" for everything, or array like ["pending","running"]. Default: active + recent.
limitinteger
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.

Parameters (1)

taskIdstringrequired
Task id from generate_image or list_generations.

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.

Parameters (1)

taskIdstringrequired
Task id to check.

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.)

Parameters (2)

assetIdstring
Optional. A specific image id (from list_my_assets, search_my_library, or show_generation). Omit to show the most recent image(s).
countinteger
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.

No parameters.

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.

Parameters (1)

countinteger
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.

Parameters (3)

querystringrequired
folderIdstring
limitinteger
Default 20.

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.

No parameters.

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.

Parameters (2)

subjectstring
What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
stylestringrequired
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.

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.

Parameters (2)

subjectstring
What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
stylestringrequired
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.

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.

Parameters (2)

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

apply_graphic_editorial_portrait

Sharp graphic editorial portrait — premium fashion-magazine grade, hard graphic composition. Classic studio or golden-hour outdoor.

Parameters (2)

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

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.

Parameters (2)

subjectstring
What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
stylestringrequired
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.

apply_wellness

Wellness / yoga / fitness / lifestyle campaign — warm amber tropical, tropical paradise cinematic, or high-key cyan beach.

Parameters (2)

subjectstring
What you want to shoot. E.g. "a woman walking through a hotel lobby" or "morning coffee on the balcony".
stylestringrequired
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.

apply_cinematic_anamorphic

ARRI Alexa anamorphic widescreen film look. Choose grade: warm golden, cool noir, or moody desaturated.

Parameters (2)

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

apply_magic_hour_portrait

Golden-hour rim-light editorial portrait. Choose camera: Canon R5 + 85mm f/1.2 or Hasselblad H6D + 80mm.

Parameters (2)

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

apply_product

Product photography. Choose: clean studio hero shot, real-world lifestyle, extreme macro detail, or top-down flat lay.

Parameters (2)

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

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.

Parameters (2)

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

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.

Parameters (7)

subjectstringrequired
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".
countinteger
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.
stylestring
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_ratiostring
Image aspect ratio. Default 9:16 (vertical, social-friendly).
modelstring
Optional explicit model. If omitted, auto-routed based on subject content (see tool description).
reference_image_urlsarray
Optional public image URLs to use as face/body/scene references.
folder_namestring
Optional Switch Studio folder name. Auto-created if missing. Defaults to the chat-derived title.

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.

Parameters (1)

taskIdstringrequired
Task id from generate_image or list_my_tasks.

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 the library. Returns a task_id per shot — poll get_video_status or list_my_videos.

Parameters (16)

subjectstring
The shot: subject + motion + scene (video needs motion language, e.g. "slow push-in").
modelstring
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.
modestring
Video mode. Must be supported by the chosen model (see list_video_models).
character_orientationstring
Motion mode only: follow the character image (default) or the reference video.
option_idstring
Optional catalog id from list_video_models (e.g. "kling-image"); use instead of model+mode.
image_urlstring
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_urlstring
End frame for frame-to-frame mode.
video_urlstring
Required for video-edit and upscale (the source clip). Must be a publicly downloadable https URL.
reference_image_urlsarray
Reference images. 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.
reference_video_urlsarray
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_urlsarray
Seedance reference/omni only: up to 3 reference audio files to drive synthesized audio. Requires at least one reference image or video.
audioboolean
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.
durationstring
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_ratiostring
e.g. 9:16, 16:9, 1:1. Must be allowed for the model (see list_video_models).
resolutionstring
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.
shotsarray
A storyboard of 1-10 DISTINCT shots. Each item takes the same fields as a single shot (subject, model, mode, image_url, etc.).

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.

No parameters.

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.

Parameters (2)

task_idstring
Task id returned by generate_video.
job_idstring
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.

Parameters (2)

countinteger
How many to return. Default 10. Max 50.
statusstring
Optional filter: submitted, processing, succeed, failed, or all.

lip_sync_video

Lip-sync audio onto a face in a video (Kling). Three steps you orchestrate: (1) action="identify-face" with video_url to detect faces (video must be MP4/MOV, 2-60 seconds, <=100MB, 720p or 1080p); (2) action="create" with session_id + a face_id + audio (sound_file as a base64 data URI, or an audio_id) + 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.

Parameters (12)

actionstringrequired
Which step to run.
video_urlstring
identify-face: the source video (MP4/MOV, 2-60s, <=100MB, 720p/1080p). Use a SwitchApp/public URL.
session_idstring
create: from identify-face.
face_idstring
create: a face_id from identify-face (one face supported).
sound_filestring
create: base64 data URI of the audio (e.g. data:audio/mpeg;base64,...).
audio_idstring
create: alternative to sound_file — an existing audio id.
sound_start_timeinteger
create: audio start, in MILLISECONDS.
sound_end_timeinteger
create: audio end, in MILLISECONDS.
sound_insert_timeinteger
create: where in the video to place the audio, in MILLISECONDS.
speech_volumeinteger
create: 0-100 (default 100).
original_audio_volumeinteger
create: 0-100 (default 0).
task_idstring
status: the task_id from create.

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.

Parameters (6)

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

voice

Manage custom voices for talking_avatar_video. action="clone" registers a voice from audio_sample_url (a 10-30 second clip) under voice_name (charged 2 credits, sample stored durably) and returns a voice_id; action="list" returns your saved voices; action="delete" removes one by voice_id. Use the returned voice_id as talking_avatar_video.voice_id.

Parameters (4)

actionstringrequired
Which operation to run.
audio_sample_urlstring
clone: a 10-30 second voice sample URL (reachable).
voice_namestring
clone: a name for the voice (unique per account).
voice_idstring
delete: the voice_id to remove.

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.

Parameters (9)

kindstringrequired
Reference type to upload.
urlstring
Public https URL to fetch server-side.
base64string
Base64 bytes (optionally a data: URL). Best for small files; large video should use presign.
mimestring
MIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac.
filenamestring
Optional source filename for extension/display.
activateboolean
Image/video: add to the active Studio reference strip. Default true. Audio never touches the strip.
frame_typestring
Image strip label: ref (default), face, body, clothes, scenery, product, typography.
presignboolean
Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled.
confirm_pathstring
The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip.

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 asynchronously via the Switch editor engine and returns a job_id — poll get_video_status or list_my_videos for the finished, downloadable video. Use this whenever the user wants to combine, join, merge, or concatenate multiple clips into one.

Parameters (5)

clip_asset_idsarrayrequired
Ordered list of your video ids (from list_my_videos). At least 2. Output order = this order.
orientationstring
landscape (1920x1080, default), portrait (1080x1920), or square (1080x1080).
fpsinteger
Frames per second. Default 30.
qualitystring
draft, standard (default), or high.
project_namestring
Optional name for the output video.

upload_media

Upload one image into the user's 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.

Parameters (3)

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

Install

claude_desktop_config.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.