Upload Reference
upload_reference_assetUpload 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. 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
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public https URL to fetch server-side. | |
| kind | Yes | Reference type to upload. | |
| mime | No | MIME for base64. Images: jpg/png/webp/gif. Videos: mp4/mov. Audio: mp3/wav/m4a/aac. | |
| base64 | No | Base64 bytes (optionally a data: URL). Best for small files; large video should use presign. | |
| presign | No | Return an upload_url to PUT the file bytes directly to (no base64). Video always; image/audio when enabled. | |
| activate | No | 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. | |
| filename | No | Optional source filename for extension/display. | |
| frame_type | No | 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). | |
| confirm_path | No | 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. |