Edit a video clip
edit_videoChange one named object or element in an existing video clip from a plain-language instruction while motion, timing, framing and cuts stay intact. Works best on 3-15s clips.
Instructions
SWAP AN OBJECT IN A VIDEO ('replace the cup with our can' + the product photo as elements) or EDIT an existing clip from a plain instruction (video-to-video): the motion, timing, framing and cut stay, the named thing changes. 'change only the mug to red', 'make it nighttime', 'restyle it as claymation'. Your words are wrapped so the model keeps everything else identical, changes only what you named and repeats that lock; lighting is kept unless the change needs new light (set lighting to force either); literal:true sends your words as written. One change per call holds best. previewFirstFrame:true edits ONE still first (one image edit; previewAt picks the second) and quotes the clip; nothing else runs until you call again, ideally with previewStill. The reply scores how well the shot held outside the change (free) and flags an edit that touched more than asked. NOT for cuts/trims/end cards (post_edit), a new video (generate_video / render_ad), translating what is SPOKEN (dub_video) or a saved creator's face (recast_motion). Translating or rewriting the on-screen words of a video laid out from a design (a template ad, a custom design) is textChanges with every line at once: one re-make of the design, about 2 credits. Best on 3-15s clips.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"video": "<video>",
"instruction": "<instruction>"
},
"name": "edit_video"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| video | Yes | the source video URL (a render, job result or list_library); a URL, not a local file path; use upload_file for local files | |
| engine | No | default auto: Seedance 2.5 Edit without a real-looking person, else Kling 4.0 Edit | |
| literal | No | true = send the instruction exactly as written, with no preserve/lock wrapper | |
| elements | No | OPTIONAL identity/product grounding (≤4): a creator portrait or the real product photo, so the edit restores the REAL thing. Describe each one in the instruction | |
| get_cost | No | true: return the price only; nothing runs or bills | |
| lighting | No | default auto: keep the source light unless the change needs new light (night, a lamp, fire). 'preserve' or 'relight' forces it | |
| faceRoute | No | 'face_lane' = the user's "I own the rights to this face" for a real person in the source clip (paid plans). Only on the user's say-so, never on your own. | |
| keepAudio | No | default true: keep the source audio; false = silent | |
| previewAt | No | second to preview (default 0); resend with previewStill | |
| reference | No | OPTIONAL image URL that anchors the MATERIAL of what changes (a fabric, a finish, a colour swatch, the real product). Only its surface is used, never its framing or light | |
| instruction | Yes | the change, in the user’s own words | |
| textChanges | No | EVERY change of on-screen words at once ([{from, to}], e.g. each line and its translation). A video laid out from a design is made again with all of them in ONE render, about 2 credits, never a video edit | |
| previewStill | No | the still a previewFirstFrame call returned; the clip then matches the changed thing to it | |
| interactionId | No | OPTIONAL: the interactionId an earlier Gemini Omni render or edit returned; the edit continues that clip on the same Omni model. If it cannot run, the video editor edits it and the reply says so. | |
| idempotency_key | No | chosen once, resent unchanged on retries: the same key never buys twice | |
| expected_credits | No | the get_cost price; refused unbilled if the live price differs | |
| previewFirstFrame | No | true = edit ONE still of the first frame first and quote the clip; the paid clip does not run |