edit timeline
Mutate a timeline with a list of typed operations applied atomically as one transaction: add, move, trim, split, slip and remove clips, ripple and close gaps, speed, clip properties, keyframes and camera moves, tracks, text, markers, links, caption settings, dimensions and frame rate. Every operation is checked before any is applied; a bad one is named by its position and nothing is written. Returns what changed, the resulting state and the new revision. Clips and tracks are named by the ids get_timeline returned. Free.
Authorizations
An API key (es_live_…) from Settings, under API keys, or an OAuth access token.
Headers
Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.
The workspace this one call acts in, when it is not the key's own.
Body
The timeline id.
Operations, discriminated on type. Frames count at the timeline's fps, and every frame field has a seconds twin (from_seconds, duration_seconds, trim_start_seconds, to_seconds, delta_seconds, at_seconds), one or the other. Clips: addClip {trackId, ref | timeline_id | clip, from?, source? [start_s, end_s], durationInFrames?, trimStart?} (from left out places it after the last clip on that track, so a run of adds builds a cut in order; a clip that would overlap another lands on a fresh track above); insertClip and overwriteClip (the fields of addClip; insert pushes what follows right on every track, overwrite clears the span on that track); replaceSource {clipId, ref}; removeClip {clipId}; rippleDelete {clipId}; rippleDeleteRange {from, durationInFrames, trackIds?}; overwriteRange {trackIds, from, durationInFrames}; rippleInsert {from, deltaFrames, trackIds?}; closeGaps {trackIds?, from?}; closeGap {trackId, atFrame}; moveClip {clipId, toFrame, toTrackId?}; trimClip {clipId, edge, deltaFrames, ripple?}; slipClip {clipId, deltaFrames}; splitClip {clipId, atFrame, newClipId}; setSpeed {clipId, speed}; updateClip {clipId, patch} (volume, opacity, holdFrames (a frame hold, 2 for on twos, up to 6), fadeIn/OutFrames, transform, grade, effects, masks, transitionIn/Out, objectFit, placeholder, category, label, the text fields; grade and effects replace whole); setKeyframes {clipId, property, keyframes: [{frame | at_seconds, value, interp?}]} (position, scale, rotation, opacity, crop, focus, volume, fx.; the list replaces that track); cameraMove {clipId, move} (zoom-in, zoom-out, pan-right, pan-left, slow-push, slow-pull, reveal, punch-in, snap-zoom, handheld, impact, drift, rise, roll-in, none); linkClips {clipIdA, clipIdB, linkId}; unlinkClips {clipId}; detachAudio {clipId}; reattachAudio {clipId}. Tracks (a fresh timeline has one visual track, id visual-main): addTrack {track: {kind: visual | audio, index, id?, clips?}}; removeTrack {trackId}; reorderTrack {trackId, index}; updateTrack {trackId, patch: {muted?, hidden?, locked?, height?}}. Markers: addMarker {marker: {from, label, kind: chapter | note, body?, durationInFrames?, id?}}; updateMarker {markerId, patch}; removeMarker {markerId}. Document: setCaptionSettings {settings}; setAspectRatio {ratio}; setDimensions {width, height}; setFrameRate {fps}; setMeta {patch}. The full reference (every field with its units and defaults, hand-built clips, the effect list with parameters, the grade shape, masks, transitions, text fields, keyframe semantics) is the skill skill-timeline-operations, read with manage_skills get.
1The revision get_timeline returned. A stale one fails with revision_conflict instead of applying; so does no revision once a user edited the timeline in the app since this connection last read it.
Optional: one sentence shown to the user beside this action.
600