list_library
List placeable media for one scope. Media still being generated is omitted.Which library to read:
private (only you), workspace (shared with the workspace), video (one video’s own library, the editor’s This video tab), default (Tella’s curated catalog and company logos), pinterest, arena or mymind (your saves in a connected service), or vintage (Tella’s vintage film shots).With
scope: "video": the video whose library to list. Requires edit access to that video. In the editor agent it defaults to the video being edited.Only return
image, video, screenshot, sound-effect, music, lut, font, or logo items. logo works with scope: "default" only, and needs query.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.- Images, videos and audio added through the API or generated with AI — includes a
sourceIdyou can pass straight toadd_overlay,add_layout,add_sound_effectorupload_clip(images included), alongside the hostedurl. Aworkspaceitem’ssourceIdworks for every member of the workspace, not just whoever uploaded it. - Custom fonts — list with
type: "font"andscope: "private"or"workspace". Fonts uploaded in the editor or through the API have an itemidyou pass asfontIdtoadd_text_overlayorupdate_text_overlay, not asourceId. - Editor-created screenshots — have type
screenshotand a hostedurl, but nosourceId. Useimport_from_urlto make a placeable capture from the original page URL. - Uploaded images in the editor — may have no source and expose only a
url, so they cannot be placed through source-based tools.
The default catalog
The default catalog
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
presetIdinstead of asourceId:sound-effectitems go toadd_sound_effect,musicitems toset_background_music. - Each item also has a
categoryfor grouping and a publicly fetchableurlfor auditioning the audio. - Filter with
type: "sound-effect"ortype: "music"; omittingtypereturns both.type: "logo"searches company logos instead. Any othertypeis 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.
Company logos
list_library and add_library_item also reach the company logos the editor’s Company logos stickers offer, provided by Brandfetch. Use them instead of searching the web for a logo.
- Call
list_librarywithscope: "default",type: "logo"andqueryset to a company’s name or domain (for example"stripe"). - Call
add_library_itemwithpresetIdset to the brand’spresetId, its domain (for example"stripe.com"), instead ofsourceId. - Place the returned
image’ssourceIdwithadd_overlayor as a layout’smedia, like any other image.
- Each item is a brand, with its
name, its domain aspresetId, and a small preview of its icon asurl. - The logo stays hosted by Brandfetch and is not saved to a library, so
scopeandvideoIdare ignored. The image is named after the brand unless you passname. - A
presetIdthat isn’t a domain, or one passed together withsourceId, is an error.
Pinterest, Are.na and mymind
Once you connect Pinterest, Are.na or mymind under Settings → Connections,list_library and add_library_item also reach the images you saved there. See Add saved images from Pinterest, Are.na and mymind for connecting them.
- Call
list_librarywithscope: "pinterest","arena"or"mymind", and optionallyqueryto search your saves. Withoutqueryyou get your newest saves.- To read one board, channel or space, pass
collection: its name, itsid, or its address. A pasted Are.na link can point to anyone’s public channel. - To see which boards, channels or spaces you have, pass
type: "collection".
- To read one board, channel or space, pass
- Call
add_library_itemwithfromset to the same service andsourceIdset to the item’sid. Tella copies the image into Tella. - Place the returned item’s
sourceIdwithadd_overlayoradd_layout, like any other image.
list_library only, with a service scope: one of your Pinterest boards, Are.na channels or mymind spaces, by its name, id or address. Lists its images instead of your newest saves, and adds the collection (its id, name, description and count) to the result. query is ignoredadd_library_item only: pinterest, arena or mymind. sourceId is then the item’s id from list_libraryadd_library_item with scope: "video": the video whose media library (the editor’s “This video” tab) the item is saved to, for an uploaded source or, with from, a Pinterest, Are.na or mymind image or a vintage shot. Requires edit access to that video. In the editor agent it defaults to the video being edited- A service scope returns one page with no
cursor. Items have typeimage, orscreenshotfor a mymind web page or article, plus thelinkthey point to and asummarywith the save’s description. mymind items also carry itstags. - With
type: "collection", items are your boards, channels or spaces instead, each with itsname,summary(its description) andcountof saves. Pass one’sidascollectionto list its images. - If
collectionmatches none of yours, the error lists the ones you have. - Only images can be brought in: Pinterest image pins, Are.na image blocks, and mymind images or the screenshot mymind took of a saved page.
- With
from,scopecan also bevideoto save the image to one video’s library instead ofprivate(default) orworkspace. - A service you haven’t connected returns a not-connected error until you connect it in Settings → Connections.
Vintage videos
list_library and add_library_item also reach Tella’s catalog of public-domain vintage film footage, the shots in the editor’s Vintage videos library. No connection is needed.
- Call
list_librarywithscope: "vintage". Passqueryto search shots by what they show (for example"steam train"), or omit it to browse featured films. Keep paging withcursorwhile it is present. - Call
add_library_itemwithfrom: "vintage"andsourceIdset to the shot’sid. Tella copies the shot into yourprivate(default) orworkspacelibrary, or withscope: "video"into that video’s library, named after the film. - Place the returned item’s
sourceIdwithadd_layout(as media for B-roll) oradd_overlay, like any other video.
- Each item is one shot of type
video, with a previewurl,durationMs,dimensions, and the film’s archive page aslink.
import_from_url
Bring media into Tella from a link. A public web page is captured above the fold at 1920×1080, a single post on X, Instagram, LinkedIn or TikTok is cropped to its embed card, and a link to a single video is downloaded as the video itself. Only import media you own or have the rights to use. Private pages, social profiles or feeds, and private, members-only or age-restricted videos are not supported.Record a scrolling web page as video instead of a still. Ignored for social posts and video links.
Save into this video’s own library instead of your private library. You must be able to edit it. Required for video links
{import: {id, status, error?, item?}}. Page and post captures finish within the call (up to two minutes) with status: "completed" and the item: type image for a still, video for a scrolling page. A video link returns status: "running"; poll get_import_status every 5-10 seconds until it is completed or failed. Place item.sourceId with add_overlay, add_layout or apply_video_edits; importing does not edit a video by itself. Reuse the same idempotency key when retrying to avoid duplicate imports.
capture_screenshot, which this replaces, still works for clients that already use it.
get_import_status
Returns the same{import: ...} shape. Start a new import to retry a failed one.
add_library_item
Save an uploaded source to the library. Callcreate_source first, PUT the bytes to the returned uploadUrl, then pass the sourceId here.
In place of
sourceId: a logo item’s presetId (the brand’s domain) from list_library. Returns that company’s logo as a placeable image; see Company logosDisplay name shown in the library — defaults to the item’s type, or the family declared inside the file for a font
private (default) or workspace to share it with everyone in the workspace — workspace requires an owner or member roleExpected item type — the type is taken from the source’s own kind, and supplying a value that disagrees is an error
kind: "lut" source, Tella validates the uploaded 3D .cube file before saving it. LUT_3D_SIZE must be at most 65; invalid files are rejected. The returned item id can be passed to set_clip_filters, and the LUT also appears in the editor’s Filters panel.
For a kind: "font" source, Tella validates the uploaded TrueType (.ttf) or OpenType (.otf) file before saving it. Fonts must be at most 20 MB; invalid files are rejected. Unless you pass name, the item takes the family name declared inside the file, with Italic appended for italic fonts. The font appears in the editor’s font picker, and its item id is the fontId accepted by text overlays.