WIwithchima
Library

List library items

Changed on

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

Query parameters

scope'private' | 'workspace' | 'default' | 'pinterest' | 'arena' | 'mymind' | 'vintage' 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), pinterest, arena or mymind (the images you saved in that service, once you connect it under Settings → Connections), or vintage (Tella's catalog of public-domain vintage film shots). Bring a pinterest, arena, mymind or vintage item 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, mymind or vintage only: words to search for. Omit to list your newest saves, or with vintage, to browse featured films.

Example:mountain logo
collectionstring

With scope=pinterest, arena or mymind only: one of your boards, channels or spaces, by its name, id or address (an Are.na channel can be anyone's public one). Lists its images, and adds the collection with its description to the response; query is ignored.

Example:Moodboard
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. vintage pages through its results.

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

  • 0cc3fcd307adRevision changes
    • info

      added the new optional query request parameter collection

  • e6d5eb99c711Revision changes
    • warning

      added the new vintage enum value to the // response property for the response status

    • info

      added the new enum value vintage to the query request parameter scope