Skip to main content
Glama
Sign In

switch

by ai.switchapp
OverviewDiscussionsAdmin

Upload Reference

upload_reference_asset

THE upload door for references. Upload an image, video, or audio reference into your Switch cloud and get an opaque asset_id (never a raw storage URL) to pass in reference fields. Pictures of real people need nothing extra: Switch checks every picture when it is used and sends a face through the protected face path automatically, in its own place. First inspect the asset and record what its actual chip controls. Preserve its thumbnail, media type, order, and role; uploading never authorizes replacing the visual chip with text or silently dropping, merging, reordering, converting, or repurposing it. A clear speaking and moving video is usually strongest for realistic identity, performance, motion, and voice when supported; still images sharpen appearance, wardrobe, products, logos, typography, and scenes. Pass kind=image|video|audio. Returns reference_image_urls / reference_video_urls / reference_audio_urls for generate_image and generate_video. Uploads stay separate from active Studio references by default, including images uploaded for video work. Set activate=true only when the user explicitly asks to add this image to the Studio image workspace. Video and audio never touch the Studio strip. 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 record it — works for image, video, and audio. base64/url is only for tiny inline files.

Input Schema

NameRequiredDescriptionDefault
urlNoPublic https URL to fetch server-side (never a file path: a path on a disk or in a sandbox cannot be fetched). Example: "https://example.com/cat.png".
kindYesReference type to upload.
mimeNoMIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac.
base64NoBase64 bytes (optionally a data: URL). Best for small files; large video should use presign.
presignNoReturn an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled.
activateNoImage only. Set true only for an explicit user request to add this image to the Studio image workspace. Default false: upload and return a reusable reference without changing Studio. On presigned uploads, set this on the confirm_path call. Video and audio never activate Studio.
filenameNoOptional source filename for extension/display.
frame_typeNoOptional Studio strip label when activate=true: ref (default), face, body, clothes, scenery, product, typography. Not needed for faces; Switch finds faces in every picture by itself and protects them (KYC-verified accounts).
confirm_pathNoThe storage_path from a presign call, after you PUT the file — verifies the object and records it; only activate=true on this call adds an image to Studio.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / url / description
      Previous value: -"Public https URL to fetch server-side."New value: +"Public https URL to fetch server-side (never a file path: a path on a disk or in a sandbox cannot be fetched). Example: \"https://example.com/cat.png\"."
  2. Changed1 schema field changed
    • changedInput schema / properties / frame_type / description
      Previous value: -"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)."New value: +"Optional Studio strip label when activate=true: ref (default), face, body, clothes, scenery, product, typography. Not needed for faces; Switch finds faces in every picture by itself and protects them (KYC-verified accounts)."
  3. Changed3 schema fields changed
    • addedInput schema / properties / activate / default
      Added value: +false
    • changedInput schema / properties / activate / description
      Previous value: -"Image only: add to the active Studio reference strip. Default true. The strip is photos only — video and audio never touch it regardless of this flag."New value: +"Image only. Set true only for an explicit user request to add this image to the Studio image workspace. Default false: upload and return a reusable reference without changing Studio. On presigned uploads, set this on the confirm_path call. Video and audio never activate Studio."
    • changedInput schema / properties / confirm_path / description
      Previous value: -"The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip."New value: +"The storage_path from a presign call, after you PUT the file — verifies the object and records it; only activate=true on this call adds an image to Studio."
  4. Changed1 schema field changed
    • changedInput schema / properties / activate / description
      Previous value: -"Image/video: add to the active Studio reference strip. Default true. Audio never touches the strip."New value: +"Image only: add to the active Studio reference strip. Default true. The strip is photos only — video and audio never touch it regardless of this flag."
  5. Changed1 schema field changed
    • changedInput schema / properties / frame_type / description
      Previous value: -"Image strip label: ref (default), face, body, clothes, scenery, product, typography."New value: +"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)."
  6. Changed2 schema fields changed
    • changedInput schema / properties / confirm_path / description
      Previous value: -"kind=video only: the storage_path from a presign call, after you PUT the file — adds it to your strip."New value: +"The storage_path from a presign call, after you PUT the file — verifies the object, records it, and adds it to your strip."
    • changedInput schema / properties / presign / description
      Previous value: -"kind=video only: return an upload_url for a large direct upload instead of sending base64."New value: +"Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled."
  7. Added

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing that uploads are kept separate from the active Studio workspace by default, that video/audio never touch the Studio strip, that only an asset_id (never a raw storage URL) comes back, and that faces are routed through a protected path automatically for KYC-verified accounts.

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

Conciseness3/5

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

The purpose and routing rules are front-loaded, but the middle contains long policy-style sentences ("Preserve its thumbnail, media type, order, and role...") that read as behavior rules rather than invocation guidance, and the phrasing "sends a face through the protected face path automatically, in its own place" is muddy.

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

Completeness4/5

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

For a 9-parameter mutation tool with no output schema, the description covers the return values (reference_image_urls / reference_video_urls / reference_audio_urls), the two-call upload protocol, and Studio side effects. Only incidental details like size limits or failure handling are missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3; the description earns more by explaining the two-phase presign/confirm_path flow, that activate must be set on the confirm_path call for presigned uploads, and the tradeoff between base64 and presigned bytes.

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

Purpose4/5

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

Opens with a specific verb and resource ("THE upload door for references") and names the accepted media kinds plus the returned handle (asset_id). It does not explicitly distinguish itself from sibling uploaders such as upload_media or upload_editor_media, which is the only thing keeping it from a 5.

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

Usage Guidelines4/5

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

Gives clear routing rules: presign=true is "PREFERRED for real files" while base64/url is "only for tiny inline files," and activate=true is reserved for an explicit user request. It stops short of naming sibling upload tools to route between, so the guidance covers modes rather than tool choice.

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

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

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources