var2_magic_replace
Magic Replacer — edit an EXISTING video clip, keeping its motion. Engine: Seedance 2.5 (default) or MiniMax Hailuo 3 (engine: "minimax-h3"). Three modes: swap (Object Swap) replaces ONE named element — a product, person, outfit or prop — with what the reference image shows and keeps everything else (e.g. "put my serum bottle in her hand instead of the coffee cup", "replace the man in the red jacket with this character", "change her dress to this outfit"). transfer (Motion Transfer) keeps ONLY the motion, camera and timing and rebuilds cast + world from the references (e.g. "same dance, but this character on a beach"; keep_location=true keeps the original place). restyle keeps the people and motion and re-renders the look in a preset (e.g. "make this video anime / claymation / noir"). Use THIS tool whenever the input is an existing clip and the ask is replace / swap / recast / restyle. Use var2_create_video instead for NEW footage (text/image/reference-to-video), wan-2.7 for a free-form prompt edit of a clip, and ltx-retake to redo only a time range of a clip. Limits — seedance-2-5: source 4–30s, ≤8 reference images, 480p | 720p (default 720p), sound optional, billed per output second (= source seconds). minimax-h3: source 4–15s at 24–60 fps, ≤9 reference images (each beyond 5 costs extra), 768P | 2K (default 768P), always generates sound, billed per second of output + source clip. Trim longer clips first; output length and aspect ratio follow the source; upscale afterwards for more resolution. Do not pass a duration — the server measures the clip. Use the default engine unless the user asks for MiniMax / Hailuo / H3 or 2K output. Tips: character refs work best as a clean full-body photo or a multi-angle character sheet on a plain background (make one first with var2_create_image, model gpt-image-2, character-sheet prompt). In swap mode name the target concretely ("the blue mug on the desk") — or call first with analyze_only=true (free) to get the detected subjects with ids like "s2" plus a credit quote, then pass target:"s2". The scene analysis is saved per clip, so later calls on the same video_url reuse it instantly and the subject ids stay the same. For a cost estimate without analysis use var2_estimate_cost with model_id "magic-replacer", type "video-to-video", params {duration:, resolution, engine}. Returns a video placeholder (poll with var2_get_video_result). Reply in ONE short sentence + the share link; do not narrate tool calls.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | swap = replace one element, keep the rest. transfer = keep only motion/camera/timing, new cast + world from references. restyle = same people + motion, new look (needs preset, a style reference or an instruction). | |
| engine | No | Render engine. seedance-2-5 (default): 4–30s clips, 480p/720p, sound optional. minimax-h3 (MiniMax Hailuo 3): 4–15s clips at 24–60 fps, up to 9 reference images, 768P/2K, always with sound. | |
| preset | No | Style preset for restyle (and optionally transfer). | |
| target | No | swap: what to replace — a concrete description ("the coffee cup in her right hand") or a subject id from analyze_only ("s2"). Required for swap unless a reference has `replaces` or the instruction says it. | |
| analysis | No | Optional and rarely needed: the `analysis` object from a previous analyze_only call for the SAME video_url, passed back verbatim. The server already saves each clip's analysis and reuses it automatically. | |
| video_url | Yes | Source clip, 4–30s MP4/MOV, var2-hosted: storage URL, var2 share link (www.var2.ai/video/<id>) or placeholder_id — auto-resolved. Third-party links (dropbox/CDN/etc.): import first with var2_upload_asset (url); local files: upload first. | |
| references | No | Rich form: reference images (combined with reference_image_urls — up to 8 on seedance-2-5, 9 on minimax-h3), each with a role, optional label and what it replaces. swap and transfer need at least one. | |
| resolution | No | seedance-2-5: 480p | 720p (default 720p; 480p costs less than half). minimax-h3: 768P | 2K (default 768P). | |
| instruction | No | Optional free-text direction appended to the compiled prompt (e.g. "she smiles at the end", "golden-hour light"). | |
| webhook_url | No | Optional. https:// URL var2 POSTs a signed delivery to when the asset is ready (or fails). Signature header: X-VAR2-Signature: t=<unix>, v1=<hex(hmac_sha256(webhook_secret, t + "." + body))>. Retried with exponential backoff (8 attempts over ~4 days). | |
| analyze_only | No | true = FREE pre-flight: measure the clip, list detected subjects (ids like "s1") and shots, report blocking issues and quote credits per resolution. Nothing is generated or charged. Use it when the swap target is ambiguous or the user asks what it would cost. | |
| keep_location | No | transfer only: keep the source video's real location instead of rebuilding it. Default false. | |
| generate_audio | No | Default true — keep / regenerate the clip's audio, dialogue and lip-sync timing. false = silent output. | |
| idempotency_key | No | Optional. Retries with the same key never double-bill (dedupes on ai_jobs.request_id). Use a stable per-user-action value (e.g. a UUID). | |
| reference_image_urls | No | Simple form: reference image URLs, each given the default role for the mode. Use `references` instead when images play different roles. |