Skip to main content
POST
compose motion

Authorizations

Authorization
string
header
required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key
string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id
string

The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.

Body

application/json
timeline_id
string
required

The timeline id.

source_code
string

Remotion JSX source (the server compiles it; not compiled code). Leave out when placing a template, or when only saving the graphic already on clip_id.

Maximum string length: 200000
html
string

Instead of source_code: a whole HyperFrames HTML document (a paused GSAP timeline registered in window.__timelines under its data-composition-id), drawn over the frame in a sandbox. No knobs, template or save_as; the contract is in skill-motion-graphics.

Maximum string length: 200000
source_edits
object[]

With clip_id, instead of source_code or html: replacements on the code the clip holds, JSX or HTML, applied in order and compiled the same way. A find that matches no place or several refuses the call and changes nothing.

Required array length: 1 - 50 elements
template
string

Place this instead of source_code: a graphic saved in this workspace (name or id), with its saved settings and length, or a ready graphic by the id get_templates returns. The clip holds a copy of the code.

Maximum string length: 120
values
object

CONTROLS values by name, set on the clip with the code: words, colors, an image control's library ref. Over a template they change only what they name.

save_as
string

Save the graphic this call leaves on the timeline under this name for the workspace, its code, settings and length together; an existing name is overwritten. With clip_id and nothing else, saves that clip as it is.

Maximum string length: 60
clip_id
string

Rewrite the graphic on this clip instead of adding another. It keeps its place, its length, its track and its fades, and control values a user changed are kept. This is how a graphic is revised.

placement
object

Where a new clip goes: { from (frame, default 0), duration_frames (default the saved graphic's length, else three seconds) }, or from_seconds and duration_seconds. Goes on the top graphics track when free. Not with clip_id.

props
object

Only description is read, as the clip's label. Values live in the source; the ones worth changing later go in its CONTROLS list, set with values here or later with edit_timeline updateClip {values}.

context
string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

ok
any
required
data
object
required
meta
object
required
media
object[]