Library

The library is where reusable media lives — images, videos, screenshots, sound effects, music, LUTs and custom fonts. It is the same set the editor’s Media library and Sound effects panels show, plus the custom fonts available in the font picker.

​

list_library

List placeable media for one scope. Media still being generated is omitted. What comes back depends on where the item came from:

• Images, videos and audio 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.
• Custom fonts — list with type: "font" and scope: "private" or "workspace". Fonts uploaded in the editor or through the API have an item id you pass as fontId to add_text_overlay or update_text_overlay, not a sourceId.
• Editor-created screenshots — have type screenshot and a hosted url, but no sourceId. Use import_from_url to 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

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.

​

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.

1. Call list_library with scope: "pinterest", "arena" or "mymind", and optionally query to search your saves. Without query you get your newest saves.
2. Call add_library_item with from set to the same service and sourceId set to the item’s id. Tella copies the image into Tella.
3. Place the returned item’s sourceId with add_overlay or add_layout, like any other image.

• A service scope returns one page with no cursor. Items have type image, or screenshot for a mymind web page or article, plus the link they point to. mymind items also carry its summary and tags.
• 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, scope can also be video to save the image to one video’s library instead of private (default) or workspace.
• 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.

1. Call list_library with scope: "vintage". Pass query to search shots by what they show (for example "steam train"), or omit it to browse featured films. Keep paging with cursor while it is present.
2. Call add_library_item with from: "vintage" and sourceId set to the shot’s id. Tella copies the shot into your private (default) or workspace library, named after the film.
3. Place the returned item’s sourceId with add_layout (as media for B-roll) or add_overlay, like any other video.

• Each item is one shot of type video, with a preview url, durationMs, dimensions, and the film’s archive page as link.
• A vintage shot can’t be saved with scope: "video".

​

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. Returns {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. Call create_source first, PUT the bytes to the returned uploadUrl, then pass the sourceId here. For a 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.

​

remove_library_item

Remove an item from the library. This removes the library entry only — clips already using the underlying source keep working.