edit_video operations

edit_video takes a list of operations. Each one is an object with an op name and that operation’s arguments:

{
  "job_id": "…",
  "operations": [
    { "op": "set_caption_style", "font_size": 64, "position": "bottom" },
    { "op": "set_track_enabled", "role": "bgm", "enabled": false }
  ]
}

There are 33 operations. They apply in order, atomically: if any one would leave the video invalid, the whole batch writes nothing.

Read before you write

Most operations address something by id — an item, a track, an asset. Call get_video_edit_state first to get the real ids. An operation that matches nothing comes back as a warning rather than an error, so a wrong id is easy to miss if you aren’t reading them.

This page is generated

Every operation, argument and enum value below comes from the same registry the endpoint validates against. If it’s documented here, it’s accepted; if the registry changes, the build fails until this page catches up.

Captions

Captions are edited through their shared style, not item by item.

set_caption_styleChange how the captions look — preset, font, size, colour, position.

Argument	Type	Description
style_id	string	Caption style id (omit to change every caption style).
preset	string	One of: pop, glow, bounce, colorwave, boxed, highlight, typewriter, clean, classic.
font_family	string	Font family name.
font_size	number	In video pixels.
font_weight	string	One of: normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900.
text_transform	string	One of: none, uppercase, lowercase, capitalize.
fill	string	Text colour (hex).
position	string	One of: top, bottom, center.
margin_v	number	Distance from its edge, in pixels.
max_lines	number	Lines on screen at once (1-6).
background_color	string	Background colour (hex), or null to clear it.
shadow	boolean
karaoke_mode	string	One of: word, syllable, none.
highlight_fill	string	Karaoke highlight colour (hex).

scale_caption_sizeMake the captions bigger or smaller by a multiplier.

Argument	Type	Description
factor required	number	1.25 = 25% bigger, 0.8 = smaller.
style_id	string	Caption style id (omit to change every caption style).

set_captions_enabledTurn the captions on or off.

Argument	Type	Description
enabled required	boolean	On or off.

set_caption_textFix the wording of one caption.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
text required	string	The corrected caption line.

apply_caption_override_to_allGive every caption the same position and size tweak (after nudging one into place).

Argument	Type	Description
caption_x	number	Horizontal centre in video pixels.
caption_y	number	Top edge in video pixels.
caption_scale	number	Multiplier on the style's font size.
caption_max_width	number	Text box width cap, in video pixels.
except_item_id	string	Caption to leave alone — usually the one already positioned.

Graphics

The overlay cards — their copy, their theme and how they display.

set_graphic_contentFix or reword the text inside a graphic.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
content required	object	Field → new value, e.g. {"quote": "…", "speaker": "…"} or {"value": "58%", "label": "of readers"}.

set_graphics_themeChange the brand look of every graphic — colours, corners, font, animation speed.

Argument	Type	Description
brand_name	string
primary_color	string
secondary_color	string
accent_color	string
background_color	string	Background colour (hex), or null to clear it.
text_color	string
font_family	string	Font family name.
corner_style	string	One of: sharp, rounded, pill.
shadow_preset	string	One of: none, subtle, medium, bold.
animation_speed	string	One of: fast, normal, slow.

set_graphic_codeLand revised Remotion code for a dynamic graphic.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
tsx_code required	string	The revised Remotion TSX, as returned by the graphic-revision capability.
editable_props	array	Editable-prop descriptors that came back with the code.

set_graphic_displayChange how a graphic is presented — overlay or full-screen takeover, where it sits, its takeover backdrop.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
display_mode	string	One of: takeover, overlay, speaker_pip.
graphic_position	string	One of: center, lower_third, upper_third, full_screen.
takeover_background_color	string	Backdrop colour (hex) behind a takeover graphic.
box_x	number	Graphic box left edge, in video pixels.
box_y	number	Graphic box top edge, in video pixels.
box_width	number	Graphic box width, in video pixels.
box_height	number	Graphic box height, in video pixels.

Assets

The registry of files a video draws on.

add_assetRegister a file (a clip, image, or audio track) so it can be placed on the timeline.

Argument	Type	Description
url required	string	Absolute http(s) URL of the file.
asset_type	string	Media type of the file. One of: video, audio, image.
asset_id	string	Asset id (e.g. broll_001), from the edit state — not an item id.
width	number	Width in pixels.
height	number	Height in pixels.
duration_seconds	number	Length of the source file in seconds.

replace_assetSwap the file behind an existing asset, keeping every placement that references it.

Argument	Type	Description
asset_id required	string	Asset id (e.g. broll_001), from the edit state — not an item id.
url required	string	Absolute http(s) URL of the file.
asset_type	string	Media type of the file. One of: video, audio, image.
width	number	Width in pixels.
height	number	Height in pixels.
duration_seconds	number	Length of the source file in seconds.

set_asset_metaCorrect an asset's dimensions or duration (e.g. after probing the real file).

Argument	Type	Description
asset_id required	string	Asset id (e.g. broll_001), from the edit state — not an item id.
width	number	Width in pixels.
height	number	Height in pixels.
duration_seconds	number	Length of the source file in seconds.

Tracks

Whole lanes — mute one, change its level, add or remove it.

set_track_enabledTurn a whole lane on or off (e.g. drop the music or the b-roll).

Argument	Type	Description
enabled required	boolean	On or off.
track_id	string	Track id, when addressing one specific lane.
role	string	Lane role — the usual way to address a lane. One of: main, broll, graphics, branding, narration, voiceover, bgm, sfx, primary, translation, color, blur, lut, curves.
track_type	string	Address every track of a type. One of: visual, audio, captions, effects.

set_track_volumeSet the level of a whole audio lane.

Argument	Type	Description
volume required	number	0 = silent, 1 = unchanged, up to 2.
track_id	string	Track id, when addressing one specific lane.
role	string	Lane role — the usual way to address a lane. One of: main, broll, graphics, branding, narration, voiceover, bgm, sfx, primary, translation, color, blur, lut, curves.
track_type	string	Address every track of a type. One of: visual, audio, captions, effects.

set_track_soloSolo an audio lane in the mix.

Argument	Type	Description
solo required	boolean	Solo an audio lane. Not exclusive — several can be soloed at once.
track_id	string	Track id, when addressing one specific lane.
role	string	Lane role — the usual way to address a lane. One of: main, broll, graphics, branding, narration, voiceover, bgm, sfx, primary, translation, color, blur, lut, curves.
track_type	string	Address every track of a type. One of: visual, audio, captions, effects.

add_trackAdd an empty lane.

Argument	Type	Description
track_type required	string	Address every track of a type. One of: visual, audio, captions, effects.
role required	string	Lane role — the usual way to address a lane. One of: main, broll, graphics, branding, narration, voiceover, bgm, sfx, primary, translation, color, blur, lut, curves.
name	string	User-facing lane label, e.g. "B-roll 2".

remove_trackDelete a lane and everything on it.

Argument	Type	Description
track_id required	string	Track id, when addressing one specific lane.

rename_trackRelabel a lane.

Argument	Type	Description
track_id required	string	Track id, when addressing one specific lane.
name required	string	User-facing lane label, e.g. "B-roll 2".

Transitions

How one shot becomes the next.

set_transitionsRestyle the transitions already in the cut.

Argument	Type	Description
kind required	string	"cut" removes the effect. One of: cut, crossfade, fade_through_black, whip_pan, zoom_punch, smooth_zoom, slide, wipe, clock_wipe, flip, glitch, light_leak, film_burn.
transition_seconds	number	How long each transition runs.
track_id	string	Track id, when addressing one specific lane.

set_item_transitionSet the transition on one item — how it enters, how it leaves, or a cut between two.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
slot	string	Which end of the item. Ignored when pair_item_id is given (that is always out→in). One of: in, out, both.
pair_item_id	string	The item on the other side of a cut. Given, the same transition is written to this item's `out` and that item's `in`.
kind	string	"cut" removes the effect. One of: cut, crossfade, fade_through_black, whip_pan, zoom_punch, smooth_zoom, slide, wipe, clock_wipe, flip, glitch, light_leak, film_burn.
transition_seconds	number	How long each transition runs.
transition_direction	string	One of: left, right, up, down.
transition_easing	string	One of: linear, ease-in, ease-out, ease-in-out, spring.
transition_intensity	number	0 subtle → 1 strong.

remove_transitionTurn a transition back into a hard cut.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
slot	string	Which end of the item. Ignored when pair_item_id is given (that is always out→in). One of: in, out, both.
pair_item_id	string	The item on the other side of a cut. Given, the same transition is written to this item's `out` and that item's `in`.

Items

Individual clips on the timeline — their timing, source and levels.

add_itemPlace a registered asset on the timeline — b-roll, a logo, a music bed, or a sound effect.

Argument	Type	Description
asset_id required	string	Asset id (e.g. broll_001), from the edit state — not an item id.
start_seconds required	number	Start time on the finished video's timeline.
end_seconds required	number	End time on the finished video's timeline.
source_start_seconds	number	Where to start inside the source file. Vary it per placement so one long clip yields different shots.
role	string	Lane role — the usual way to address a lane. One of: main, broll, graphics, branding, narration, voiceover, bgm, sfx, primary, translation, color, blur, lut, curves.
track_id	string	Track id, when addressing one specific lane.
volume	number	0 = silent, 1 = unchanged, up to 2.
description	string	Short note about what the shot shows.
item_id	string	Timeline item id (e.g. broll_item_001), from the edit state.

remove_itemTake an item off the timeline.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.

set_item_timingMove an overlay or graphic to a different moment, or change how long it holds.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
start_seconds	number	Start time on the finished video's timeline.
end_seconds	number	End time on the finished video's timeline.

set_item_sourceChoose which part of the source file an item plays (its in-point).

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
source_start_seconds required	number	Where to start inside the source file. Vary it per placement so one long clip yields different shots.
source_end_seconds	number	Optional out-point inside the source file.

set_item_volumeChange how loud one item is.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
volume required	number	0 = silent, 1 = unchanged, up to 2.

set_item_fadeFade an item's audio in or out.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
fade_in_seconds	number	Seconds to ramp up from silence.
fade_out_seconds	number	Seconds to ramp down to silence.

set_item_dataUpdate an item's descriptive payload — a music bed's title/artist/loop, a shot's description.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
data required	object	Field → new value, merged over the existing payload. e.g. {"title": "Hype Bed", "artist": "", "provider": "elevenlabs", "loop": true}.

set_item_transformMove or resize a visual item on screen (its box, not its timing).

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
x	number	Left edge in video pixels.
y	number	Top edge in video pixels.
w	number	Box width in video pixels.
h	number	Box height in video pixels.

move_itemMove an item to a different moment on its own lane.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
start_seconds required	number	Start time on the finished video's timeline.
ripple	boolean	Also slide the items after it, closing the gap left behind and opening one at the destination. Off by default; needs an explicit target.

duplicate_itemCopy an item, placing the copy immediately after it.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
start_seconds	number	Start time on the finished video's timeline.

split_itemCut an item in two at a given moment.

Argument	Type	Description
item_id required	string	Timeline item id (e.g. broll_item_001), from the edit state.
split_seconds required	number	Where to cut, on the finished video's timeline.

Project

Settings that apply to the whole video.

set_metaRename the video.

Argument	Type	Description
title	string	The video's title.
aspect_ratio	string	One of: 9:16, 16:9, 1:1.