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 and background music without uploading your own audio. Library items appear in the same Media library, Sound effects and Background music 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.

Browse curated background music

Set scope to default and type to music to list the same curated tracks available in the editor’s background music panel:

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

Each item includes a presetId, category (Calm, Energetic, Focused or Playful), durationMs, and a public url you can use to preview the track. Omitting type returns sound effects and music together. Use the presetId to set the video’s background music without creating or uploading a source:

curl -X PUT "https://api.tella.com/v1/videos/vid_abc123/background-music" \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "calm-product-tour",
    "volume": 0.2
  }'

Pass exactly one of presetId or sourceId. The track’s name defaults to the preset’s name.

The default catalog contains sound effects and music 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 uploaded 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, sound effects and AI-generated items include a sourceId; curated sound effects and music tracks use presetId instead. Music and LUT items saved from the editor 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.

Generate media with AI

When there is nothing to upload, generate it. POST /v1/library/generations starts the same AI image or sound effect generator the editor’s media panels use, and saves the result as a private library item.

curl -X POST https://api.tella.com/v1/library/generations \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "prompt": "A watercolor illustration of a lighthouse at dawn"
  }'

The response is 202 Accepted with a generation whose id is the library item being filled in, plus your weekly allowance (limit, remaining, resetAt). Pass "type": "sound-effect" for a sound effect. For an image, an optional referenceSourceId — the sourceId of an image source you uploaded, or of an image library item — guides the generation. Generation is asynchronous. Poll GET /v1/library/generations/{id} every few seconds (images usually take 30-90 seconds, sound effects 10-30) until status is completed:

curl "https://api.tella.com/v1/library/generations/mi_abc123def456" \
  -H "Authorization: Bearer $TELLA_API_KEY"

On completed, generation.item is the finished library item. Pass its sourceId anywhere a source is accepted — an image overlay, a layout’s b-roll media, or a clip’s sound effects — and it also appears in GET /v1/library?scope=private. On failed, generation.error provides a sanitized, human-readable reason. It may identify a content-safety rejection or timeout, or report a generic failure. Do not parse this text for machine handling. A failed generation cannot be resumed, so start a new one.

Each generation counts against your plan’s weekly AI generation allowance, the same one the editor uses. Once it is exhausted the endpoint answers 403 with the reset time in the message.

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

MCP Tools

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

Browse curated background music

Reuse a library item

Generate media with AI

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

​Browse curated background music

​Reuse a library item

​Generate media with AI

​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

Browse curated background music

Reuse a library item

Generate media with AI

Remove a library item