Update clips (batch)
update_clipsUpdate one or more clips in a single call — background, transition, duration, title, visibility, position, and (video clips) the footage transform via video_styling. Always batch.
Each entry: { clip_index, duration?, title?, background_color? | background?, transition?, hidden?, position?, voiceover_volume?, video_styling? }
duration: sets the clip's length WITHOUT rescaling anything (unlike generating speech, which rescales the whole clip). A shrink clamps every end_time past the new end to it; a grow carries an element that ended at the old end to the new end and leaves the rest where they were. A placed trim animation keeps its animation_duration: it holds its last frame on a grow and is cut on a shrink; only a stretch animation placed to fit keeps filling its window at the same speed. Keyframes keep their timestamps. Each clip's result lists what moved as extended / clamped.
voiceover_volume: 0-100. This is how you make a clip SILENT — set 0 to mute the narration while keeping the text and its word timings. get_clip and get_project report the current value, so read it before muting to restore it later. There is no "delete voiceover" tool; muting is the supported way.
background_color: hex (keeps the existing pattern/image, changes color). background: full object from find(type='backgrounds') — replaces the whole background.
transition: { type, duration, direction?, color?, bezier? }, or null to remove. Set on the OUTGOING clip — the transition plays at the END of clip_index, into the next clip. Types: circleWipe, rainbowWipe, cornerWipe, stack, colorWipe, dissolve, pushPull, fadeToColor, flip. Directions: rainbowWipe/cornerWipe take topLeft|topRight|bottomLeft|bottomRight; colorWipe left|right; stack/pushPull left|right|top|bottom; flip (3D card turn) horizontalLeft|horizontalCenter|horizontalRight|verticalTop|verticalCenter|verticalBottom. bezier [x1,y1,x2,y2] eases flip.
position: move the clip to a new zero-based index. Moves apply FIRST (in array order), then property patches — keep reorders in a separate call from property edits so indices stay predictable.
video_styling (VIDEO CLIPS ONLY — ignored on slide clips): reposition/resize the clip's recording on the canvas, e.g. into a designed window slot. { position?: [cx, cy], size?: [w, h] } as canvas fractions 0–1 ([1,1] = full-bleed, position is the footage CENTER), plus crop? and border?. Fields merge onto the clip's existing video_styling.
video_styling.border frames the recording, as the editor's Stroke panel does: omnibox (browser toolbar with a URL bar over the footage — e.g. { type: "omnibox", color: "#0052CC" }), browser (window chrome), notch (phone notch), solid (plain stroke; takes stroke), glass, animated, or none. Width and color default per type like the editor; a bare { color } restyles the current border.
Concurrency: parallel-safe per clip — all property updates land in ONE save. Safe to fan out across DIFFERENT clips. Do NOT run concurrently with element/voiceover edits on the SAME clip, or whole-project mutations (add_clips, add_audio, update_project). When adding audio + resizing clips, run update_clips BEFORE add_audio.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| updates | Yes | One entry per clip to update. | |
| project_id | Yes | Project ID |