Library

List library items

Returns a page of reusable media saved to the library — images, videos, screenshots, sound effects, music and LUTs — for one scope. Items added through the API include a sourceId you can pass anywhere a source is accepted, including images. Editor-added images, screenshots, music and LUTs expose a hosted url instead. URL captures from POST /v1/library/screenshots are placeable image or video items. Media still being generated in the editor is omitted. scope=default returns Tella's curated sound effect and background music catalogs instead of stored media: those items carry a presetId to place them with (sound-effect items via POST /v1/videos/{id}/clips/{clipId}/sound-effects, music items via PUT /v1/videos/{id}/background-music), a category, and a publicly fetchable url for previewing, and arrive as a single page; filter with type=sound-effect or type=music, or omit type for both. Tella's default backgrounds are not part of this catalog — they are placed as a background rather than as a source, and are listed by GET /v1/backgrounds. scope=pinterest, scope=arena and scope=mymind list the images you saved in that service once you connect it under Settings → Connections: your newest saves, or matches for query, as one page. Their id is the service's own ID; bring one into Tella with POST /v1/library and from before placing it. A service you haven't connected returns 503 unavailable.

get/v1/library

Request

  • Base URL: https://api.tella.com
  • URL: https://api.tella.com/v1/library
  • Auth: HTTP bearer

Query parameters

scope'private' | 'workspace' | 'default' | 'pinterest' | 'arena' | 'mymind' required

Which set of media to read: private (only visible to their creator), workspace (shared with everyone in the workspace), default (Tella's curated sound effect and background music catalogs, which hold no other media type), or pinterest, arena or mymind (the images you saved in that service, once you connect it under Settings → Connections; bring one in with POST /v1/library and from)

Example:private
type'image' | 'video' | 'sound-effect' | 'music' | 'lut' | 'screenshot' | 'font'

The kind of media the item holds

Example:video

Only return items of this type. With scope=default only sound-effect and music are valid, since the curated catalog holds no other media type; omitting it returns both.

querystring

With scope=pinterest, arena or mymind only: words to search your saves for. Omit to list your newest saves.

Example:mountain logo
cursorstring

Pagination cursor from a previous response. Keep paging while cursor is present. scope=default is a fixed catalog, and pinterest, arena and mymind return a single page of your newest saves or best matches, so they never set one.

limitinteger

Items per page (1-60, default 24). Treat it as a target rather than an exact count: pages are read from storage before unlistable items are filtered out, and cursors address whole storage pages, so a response may contain somewhat more than limit. Returning the extra items is deliberate — trimming them would drop them, because the cursor has already moved past.

Example:24

Response

OK

cursorstring

Cursor for the next page. Absent when there are no more items.

Example response

{
  "items": [
    {
      "category": "Everyday",
      "durationMs": 4200,
      "id": "media_abc123def456",
      "name": "Intro camera take",
      "presetId": "cha-ching",
      "scope": "private",
      "sourceId": "su_abc123def456",
      "type": "video"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.