Skip to main content
The library is where reusable media lives — images, videos, sound effects, music and LUTs. It is the same set the editor’s Media library and Sound effects panels show.
Saving a source to the library is what makes it findable later. A source you never add is only reachable through the clips that reference it, so deleting the video takes the last handle on it with it.

​
list_library

List placeable media for one scope. Media still being generated is omitted.
​
enum<string>
required
Which library to read: private (only you), workspace (shared with the workspace), or default (Tella’s curated catalog).
​
enum<string>
Only return image, video, sound-effect, music, or lut items.
​
string
Cursor from a previous response — keep paging while cursor is present.
​
integer
Items per page (1-60, default 24). A target rather than an exact count: a page is read before unlistable items are filtered out, so a response may hold somewhat more. Page until cursor is absent rather than counting items.
What comes back depends on where the item came from:
  • Added through the API or generated with AI — includes a sourceId you can pass straight to add_overlay, add_layout, add_sound_effect or upload_clip (images included), alongside the hosted url. A workspace item’s sourceId works for every member of the workspace, not just whoever uploaded it.
  • Uploaded in the editor — has no source and exposes only a url, so it can’t be placed through the API.
scope: "default" returns Tella’s curated sound effects and background music — the same tracks the editor’s panels show.
  • Presets have no source, so items carry a presetId instead of a sourceId: sound-effect items go to add_sound_effect, music items to set_background_music.
  • Each item also has a category for grouping and a publicly fetchable url for auditioning the audio.
  • Filter with type: "sound-effect" or type: "music"; omitting type returns both. Any other type is an error.
  • The catalog is fixed, so it comes back as a single page and never sets a cursor.
  • Tella’s default backgrounds are not here — they are placed as a background rather than a source, so use list_backgrounds.

​
add_library_item

Save an uploaded source to the library. Call create_source first, PUT the bytes to the returned uploadUrl, then pass the sourceId here.
​
string
required
Source ID from create_source, already uploaded
​
string
Display name shown in the library — defaults to the item’s type
​
enum<string>
private (default) or workspace to share it with everyone in the workspace — workspace requires an owner or member role
​
enum<string>
Expected item type — the type is taken from the source’s own kind, and supplying a value that disagrees is an error

​
remove_library_item

Remove an item from the library. This removes the library entry only — clips already using the underlying source keep working.
​
string
required
Library item ID from list_library
​
enum<string>
required
The library the item lives in — private or workspace