Editing tools

Editing is two tools: one that tells you what’s in the video, and one that changes it. Always call the first before the second — edits address items by id, and guessing an id gets you a warning instead of a change.

get_video_edit_state

Read a rendered video's structure so you can change it: its tracks, the ids of every b-roll clip / graphic / music item, the caption style, and the graphics theme. Call this BEFORE edit_video — the operation arguments reference these ids. Also the way to show the user their video: the result renders as a playable preview in the chat.

Parameter	Type	Description
job_id required	string	The video job id.

Returns a compact summary rather than the whole manifest: the tracks, the item and asset ids, the caption style and the graphics theme. That is everything edit_video needs to address, without spending thousands of tokens on frame-level caption timings.

edit_video

Change a rendered video by editing its manifest: add or swap b-roll, music and sound effects, caption look/size/position, lanes on/off, mix levels, graphic copy, brand colours, transition style, retiming or removing an overlay. Adding footage takes two operations — add_asset to register the file, then add_item to place it (give each placement its own source_start_seconds so one long clip yields different shots). The chat preview updates immediately — the user does NOT need a re-render to see it (the downloadable file does, via the Render button on the card). Call get_video_edit_state first so your operations reference real ids: item ids and asset ids are different namespaces. Batch every change the user asked for into ONE call.

Parameter	Type	Description
job_id required	string	The video job id.
operations required	object[]	The changes to apply, in order. Each entry names an `op` plus only the fields that op uses.
label	string	Three-to-five word name for this version, shown on the chat card, e.g. "bigger captions" or "no music".

Operations, not JSON

The agent never writes manifest JSON. It emits named operations — {"op": "set_caption_style", "font_size": 64} — which are validated against the registry and applied atomically. The full vocabulary is on its own page:

• edit_video operation reference

Four guarantees are worth designing around:

Guarantee	What it means for you
Fail closed	If the video was valid before, it’s valid after. An edit that would break it writes nothing — there is no half-applied state to clean up.
A miss is a warning	An operation matching no item returns a warning naming the id that missed, not an error. The batch still applies. Read the warnings; they’re how you learn an id was wrong.
All-miss fails	If every operation matched nothing, the call fails outright rather than reporting a hollow success.
Versioned	Each edit writes a new version. Earlier cuts stay watchable.

Targeting

By default an edit applies to every definition — the long form and every clip. That is almost always right, because clips are cut from the long form and a change to one should be in the other.

Pass target to narrow it: "long_form", or "clip:0" for the first clip.

Two things edit_video will not do

It won’t run while the job is still working. Editing a manifest that’s being written produces a race, so the call is refused until the job reaches planned.

It won’t retime captions. Caption timing comes from the transcript, which is measured from the audio. You can restyle them, resize them, turn them off and change their text — but their in and out points are not yours to move.