Skip to main content
Every item is an image, a video, an audio file or a document, uploaded or generated. Nothing has to be set up before you work in it. A workspace that uses only the timeline, or only generation, is complete as it is.

​
Naming an item

Every item has one canonical id and an 8-character ref, like XC4WBAX5, which users copy from the app. Either is accepted wherever an item is named. Pass ids back exactly as you received them. A generation returns a job id; the item it produces has its own id, created when the output is ready, and the job id also resolves as a ref for that item.

​
Getting media in

import_media has one mode per source:
  • url for hosted files, up to 20 per call. Files are deduplicated by content, and each is reported as imported, duplicate or failed. A download that passes about 20 seconds continues as a job.
  • file for bytes in the call, base64, up to 6 MB.
  • local for absolute paths on the computer running the desktop app. Nothing is uploaded.
  • presign and confirm for a file up to 5 GB the caller uploads itself with a PUT.
  • link for a page the user opens to drop files from their own computer.
Over REST, Uploads is the same path for a developer’s own client. When the footage does not exist yet, the app records it: camera, screen with voice, or both.

​
Reading media

  • search_library finds items by text over descriptions, tags, transcripts and what pictures show, with filters for type, folder, dates, labels, fields, storage and source, paged with next_cursor. duplicates_of finds near-identical files to one item.
  • search_footage finds moments inside videos and recordings, visual and spoken, as start and end times in source seconds.
  • get_items returns everything known about up to 25 items: description, tags, fields, comments, provenance, lineage, variations, versions, technical data, and which analyses are stored.
  • inspect_media returns the pixels: an image, or a video as frames in one of several layouts, with the words spoken in that span where a transcript exists. A title or description is text somebody wrote; the frames are the file itself.
  • transcribe_media, detect_beats, speakers, inspect_color and read_document each read one thing from a file, and inspect_media with a prompt has a model answer a question about a video or audio file. The result is stored on the item, so repeating the call costs nothing.
Where a file’s bytes are matters. A file that exists only on a user’s computer has no cloud copy until it syncs, and a cloud-only read says so and names the computer. See Desktop and cloud.

​
Writing metadata

update_items writes name, description, tags, typed field values and lineage onto up to 25 items per call, item by item. A failure on one item is reported beside the results of the rest. made_from records what an item was derived from. Items that are peers of one concept form a variation set.

​
Structure

Structure is optional. organize_items creates all of it in one batch, running the parts in a fixed order so one call can create a path and move items into it.
  • A folder is where an item is filed. Paths like campaigns/july are accepted wherever a folder is named.
  • A label is a workspace-wide mark that people filter by.
  • A field is a typed column on the workspace. A select field is what a board reads; a date field is what a calendar reads. update_items sets values by field name and refuses a name that does not exist.
  • A board (manage_boards) is a select field whose options are its columns. Placing a card sets that field. A calendar (manage_calendars) is a date field with a time, channels and a status of its own.
  • Versions stack one item behind another, such as v2 of a cut or a re-render. Variations sit side by side.
  • Star and hide are per item. A hidden item leaves the feed and stays in the library.

​
Brand kit

manage_brand_kit reads and writes the workspace’s colors, fonts, written direction, logos, words with their pronunciations, and pinned templates. get_workspace_overview says whether a brand kit exists. manage_public_links builds a page anyone can open without an account, from chosen items, with a layout of blocks, settings that reach the live page at once, and a record of what visitors wrote. Public pages are not indexed by search engines. Deleting a link removes the link and its activity, never the media.