Media library API

The media library API lets you keep images, videos, and sound effects available independently of any one video. You can also browse Tella’s curated sound effects without uploading your own audio. Library items appear in the same Media library and Sound effects panels used in the Tella editor.

Upload and save media

Saving new media is a three-step process:

Create a source with POST /v1/sources.
Upload the file bytes to the returned uploadUrl before it expires.
Save the returned sourceId with POST /v1/library.

Create a source

Include width and height for an image or video. Include duration in seconds for a video or audio file.

curl -X POST https://api.tella.com/v1/sources \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "video",
    "width": 1920,
    "height": 1080,
    "duration": 12.4
  }'

The response contains a sourceId, an uploadUrl, and the time when that upload URL expires.

Upload the file

Upload the original file as a single PUT request. Common image, video, and audio formats are accepted.

curl -X PUT "UPLOAD_URL" --upload-file ./intro.mp4

Add the source to the library

Use private for media only you can access, or workspace to share it with everyone in your workspace. If you omit scope, the item is saved to your private library.

curl -X POST https://api.tella.com/v1/library \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "su_abc123def456",
    "name": "Product intro",
    "scope": "workspace"
  }'

Tella infers whether the item is an image, video, or sound effect from the source. You can optionally send type to verify the expected type; the request fails if it does not match the source.

Adding items to a workspace library requires an owner or member role. Workspace viewers can list shared items but cannot add or remove them.

List saved media

List the private and workspace libraries separately by setting the required scope query parameter:

curl "https://api.tella.com/v1/library?scope=workspace&type=video&limit=24" \
  -H "Authorization: Bearer $TELLA_API_KEY"

You can filter by image, video, sound-effect, music, or lut. When the response includes a cursor, pass it in the next request and continue until no cursor is returned.

limit is a target page size. A response can contain slightly more items because Tella reads a storage page before filtering unavailable items. Follow cursor rather than relying on the item count.

Browse curated sound effects

Set scope to default to list the same curated sound effects available in the editor:

curl "https://api.tella.com/v1/library?scope=default&type=sound-effect" \
  -H "Authorization: Bearer $TELLA_API_KEY"

Each item includes a presetId, category, durationMs, and a public url you can use to preview the audio. The catalog is returned as one page without a cursor. Use the presetId to add an effect to a clip without creating or uploading a source:

curl -X POST \
  "https://api.tella.com/v1/videos/vid_abc123/clips/cl_abc123/sound-effects" \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "cha-ching",
    "startTimeMs": 2000,
    "durationMs": 1680
  }'

Pass exactly one of presetId or sourceId. Use the item’s durationMs to play the full effect.

The default catalog contains sound effects only and is read-only. Use private or workspace when adding or removing your own library items.

Reuse a library item

Items added through the API include a sourceId. Pass it to any compatible endpoint, including clips, layouts, overlays, backgrounds, and sound effects. API-added images also include a hosted url, but use their sourceId when placing them in a video. Images added in the editor may return only a hosted url. Without a sourceId, those images can be used in the editor but cannot be placed through the public API. Saved videos and sound effects include a sourceId; curated sound effects use presetId instead. Music and LUT items return a hosted URL instead of a source ID.

Save a source to the library as soon as you want to reuse it. A source that is not saved still exists after its video is deleted, but it may no longer be discoverable through the API.

Remove a library item

Pass both the library item ID and its scope:

curl -X DELETE \
  "https://api.tella.com/v1/library/media_abc123def456?scope=workspace" \
  -H "Authorization: Bearer $TELLA_API_KEY"

Removing a library item removes only its entry from the library. Existing clips and videos that use the underlying source continue to work.

Library API reference

Review all request parameters and response fields for the library endpoints.

Getting Started

Guides

API Reference

Webhooks

Media library API

Upload and save media

Create a source

Upload the file

Add the source to the library

List saved media

Browse curated sound effects

Reuse a library item

Remove a library item

Library API reference

​Upload and save media

​Create a source

​Upload the file

​Add the source to the library

​List saved media

​Browse curated sound effects

​Reuse a library item

​Remove a library item

Library API reference

Upload and save media

Create a source

Upload the file

Add the source to the library

List saved media

Browse curated sound effects

Reuse a library item

Remove a library item