Skip to main content
A timeline is a document of tracks and clips, for video. A canvas is layers on one or more slides, for images. Both are edited the same way, and a workspace holds any number of each. There is no active document, so every tool takes timeline_id or canvas_id. A project is a timeline that holds clips cut from one recording with cut_clips. Each clip is a timeline of its own with a parent_id, and edit_clips and render_clips work on a set of them.

​
Read, then write

get_timeline or get_canvas returns the document with a stable id for every clip, track or layer, and its revision. A read stops at about 60,000 characters, reports that in cut_short, and continues from next_cursor. Ranges, tracks, slides and fields narrow a read. response_format: "detailed" returns every property a clip or layer can be set to, so you can match an existing look instead of guessing it. edit_timeline and edit_canvas take a list of typed operations that apply as one transaction. Every operation is checked before any is applied. A bad one is named by its position, and nothing is written. The response says what changed and carries the new revision. The full grammar of each is a skill, Timeline operations and Canvas operations, read with manage_skills. Ids are returned in a short form. Pass them back as received.

​
Revisions

A write takes if_revision from the last read or write response. A stale revision fails with revision_conflict instead of overwriting another editor’s change, whether that editor is a user or another agent. A write with no revision fails with the same code once a user has edited the document in the app since this connection last read it. A fresh document nobody has edited accepts a write without one. Documents are live: a user may have one open, and the next agent reads whatever state was left. undo puts a document back as it stood before its last edit, or restores any kept revision, forward or back. A timeline keeps 50 revisions, a canvas 20. An edit made by someone else is named and left alone unless a revision names it.

​
Words on a clip

Words come from transcription. An empty transcript on uploaded speech means the file has not been transcribed, not that it is silent. transcribe_media with timeline_id gives the clips their words, and captions, get_transcript and remove_words read from there. remove_words shifts word indices, so re-read get_transcript before the next cut. Cleaning speech has an order: clean_audio before any cut, because the cleaned file replaces the clip’s media whole and the transcribed words stay with the original file; then remove_silence; then remove_words.

​
Keyframe tracks

A punch-in, a reframe and music ducking (auto_zoom, auto_reframe, duck_music) each write a keyframe track and replace what that track held. setKeyframes on edit_timeline writes a single property by hand. Grade and effects are replaced whole on updateClip.

​
Checking and rendering

  • check_timeline is free, except the first time it measures a file’s sound, which uses cloud processing; audio: false skips that. It reports black stretches, buried clips, trims past the end of a file, missing media, muted sound, unreadable text and the loudness of the speech.
  • inspect_timeline and inspect_canvas draw real frames of the composite, which is how an edit is verified.
  • render_timeline exports an mp4, a transparent WebM, a GIF, or an mp3 or wav. render_timeline returns a job. render_canvas files the images or the PDF in the call, and a PDF over twelve pages is a job. The item each produces is the deliverable. Through the desktop app a render runs on that computer, free, at any length and resolution. Outside it, inspect_timeline, inspect_canvas and every render use cloud processing, and a render is charged what it actually cost.
Every timeline carries its own aspect ratio, size and frame rate. setFrameRate re-times the document with every clip staying at its second. Generation settings are independent of these.

​
Templates

manage_timelines and manage_canvases can keep a finished document as a template, and get_templates lists it. A timeline kept as a template turns its picture clips into holes, and manage_timelines create with from_template and fill copies it with new files in one call. A canvas kept as a template is copied with manage_canvases create from_canvas, and its image layers are the ones to replace. get_templates also carries the catalogue the app’s Explore page shows: motion graphics, caption templates, camera moves, filters and fonts, each with the exact call that uses it. compose_motion save_as and captions generate save_template_as save a graphic or a caption look for the workspace; manage_templates renames or deletes one.