Editor state

Define a video's canvas, timeline, media references, and visual properties as JSON.

Editor state describes a video: its canvas, tracks, timed items, assets, and transitions. Use it when your application controls the video's content and layout.

Start with the complete five-second sample. It contains text and a solid background and does not require uploaded media. The Quick Start validates and exports that sample.

Document structure

Field	Purpose
`stateSchemaVersion`	State format version. Use `"v1"`.
`compositionWidth`, `compositionHeight`	Canvas dimensions in pixels.
`timebaseTicksPerSecond`	Timeline timebase. Use `240000`.
`tracks`	Ordered tracks and the item IDs on each track. Include at least one track.
`items`	Timed clips, text, shapes, effects, and other timeline items keyed by ID.
`assets`	Media metadata and locations keyed by the IDs used by items.
`transitions`	Transitions between clips.

The create-project, sync-project, and stateless-export request bodies also require stateSchemaVersion: "v1" alongside editorState. Set both version fields consistently.

Optional fields include outputRatio, globalBackground, brandRuntime, and deletedAssets. Omit optional features until your video needs them. The API reference contains the full state schema.

Time and animation

Timeline item positions use startTicks and durationTicks. Convert seconds to ticks with:

ticks = seconds × 240000

Five seconds is 1200000 ticks. Track order determines which items belong to each track; each referenced ID must exist in items.

Animatable numeric properties use a static value and an array of keyframes. Each point has timeTicks and a numeric value. This property fragment moves an item horizontally over one second:

{
  "left": {
    "value": 100,
    "keyframes": [
      { "timeTicks": 0, "value": 100 },
      { "timeTicks": 240000, "value": 400 }
    ]
  }
}

This is a property fragment, not a complete item or state document. Keep keyframes within the item's supported duration and validate the complete state after editing.

Media and captions

Media items reference entries in assets by assetId. Include the metadata required for the asset type as well as its URL. Assets explains how upload responses map to these fields.

Caption assets include captions and timingGranularity (word or line). Caption entries use millisecond timing fields; do not treat them as timeline ticks. Choose animation presets that fit the available caption timing.

Discover supported features

GET /v1/editor/capabilities lists supported animations, caption animations, transitions, effects, filters, shapes, and background presets. Use its identifiers instead of guessing preset names.

Search illustrations with GET /v1/illustrations?q=creative. Use the returned illustration name in an illustration item. The API does not turn an arbitrary prompt or uploaded document into editor state.

For agent-led authoring, use the OpenClaw plugin.

Validate before saving or exporting

Send { "editorState": ... } to POST /v1/editor/validate. The response contains valid and errors. Each error supplies a code, path, and message identifying what needs attention.

Typical failures include a missing required field, an asset reference that does not exist, a track referencing an absent item, or a transition between incompatible clips. Fix the indicated paths and validate again before creating a project or export.

The SDK may reject a schema-invalid payload locally. A successful local check does not replace server validation of the complete request and referenced resources.