Skip to main content
Every item is an image, a video, an audio file or a document, uploaded or generated. Nothing needs to be set up first. A workspace that uses only timelines, or only generation, needs nothing else.

Naming an item

Every item has one canonical id and an 8-character ref, like XC4WBAX5, that users can copy from the app. Either one works wherever a tool asks for an item, exactly as it was returned. A generation returns a job id. The item it makes gets its own id when the output is ready, and the job id also works 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 takes longer than about 20 seconds continues as a job.
  • file for bytes in the call, base64, up to 3 MB.
  • local for absolute paths on the computer running the desktop app. Nothing is uploaded during the call. With the workspace’s cloud sync on (the default), the file is also copied to the cloud while the owner’s storage has room.
  • presign and confirm for a file the caller uploads itself with a PUT: up to 5 GB of video, 500 MB of audio, 20 MB for an image, 25 MB for a document. A larger video can be added through link.
  • link for a page where the user can add files from a computer or a phone. It returns a link_id, and search_library with upload_link lists the files added through that page.
Over REST, Uploads describes the same flow for a developer’s own client. When the footage doesn’t exist yet, the app can record 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 files nearly identical to one item.
  • search_footage finds moments inside videos and recordings, by what is seen or said, as start and end times in seconds of the source.
  • get_items returns everything stored about up to 25 items: description, tags, fields, comments, provenance, lineage, group, technical data, and which analyses are stored.
  • inspect_media returns the actual picture: an image, or a video as frames in one of several layouts, with the words spoken in that span when a transcript exists. A title or description is text someone wrote, while the frames show 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 asks a model a question about a video or audio file. Transcripts, beats, speakers and document text are stored on the item, so reading them again is free, while each prompt is a new paid read.
Where a file is stored matters. A file that is 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 sets name, description, tags, typed field values and lineage on up to 25 items per call, each item separately. A failure on one item is reported alongside the results for the others. made_from records what an item was derived from. Items shown together form a group (organize_items group).

Structure

Structure is optional. organize_items creates all of it in one batch, in a fixed order, so one call can create a folder path and move items into it.
  • A folder is where an item is kept. Paths like campaigns/july are accepted wherever a folder is named.
  • A label is a tag shared across the workspace, used for filtering.
  • A field is a typed column across the workspace. Boards are built on select fields, and calendars on date fields. 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 in a column sets that field. A calendar (manage_calendars) is a date field with a time, channels and a status of its own.
  • A group links items shown together: a research document and the posts it is based on, a set of variants, slides. Each stays its own item in the library.
  • Favorite and hide are per item. A hidden item is removed from the feed but stays in the library.

Brand kit

manage_brand_kit reads and writes the workspace’s brand kits: colors, fonts, written direction, logos, pinned templates, and words the workspace spells in its own way, which transcripts are corrected to. The free plan includes one kit. get_workspace_overview says whether a brand kit exists. manage_public_links builds a page from chosen items that anyone can open without an account, with a layout of blocks and a record of what visitors wrote. Settings changes go live right away, while a layout change stays a draft until publish. Public pages are hidden from search engines. Deleting a link removes the link and its activity, but not the media.