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

Check processing

Video and audio sources start converting as soon as the upload finishes. Poll GET /v1/sources/{sourceId} every few seconds until its status is ready. While conversion is in progress, previews may answer not-ready.

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.

Use POST /v1/library/screenshots to capture a public web page or a single post on X, Instagram, LinkedIn or TikTok:

curl -X POST https://api.tella.com/v1/library/screenshots \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-page-capture-1" \
  -d '{"url":"https://www.tella.com","scroll":false}'

The request waits for the capture to finish (allow up to two minutes), then returns HTTP 201 with {item: ...}. The private library item includes a sourceId for overlays or layout media; there is nothing to upload or poll. Stills have type image. Set scroll to true to record a web page as video instead; social posts always produce stills. Private pages and social profiles or feeds are not supported. Reuse the same Idempotency-Key when retrying the same request, and use a new key when you want a new capture.

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, screenshot, sound-effect, music, or lut. Editor-created screenshot items expose a hosted url but no sourceId; use the capture endpoint below to create placeable media from the original URL. 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.

Bring in images from Pinterest, Are.na and mymind

Once you connect Pinterest, Are.na or mymind under Settings → Connections (see Add saved images from Pinterest, Are.na and mymind), you can list the images you saved there and copy one into Tella. Set scope to pinterest, arena or mymind. Add query to search your saves, or omit it for your newest ones:

curl "https://api.tella.com/v1/library?scope=pinterest&query=mountain%20logo" \
  -H "Authorization: Bearer $TELLA_API_KEY"

The response is a single page with no cursor. Each item’s id is the service’s own ID, and items include the link the save points to. mymind items also include its summary and tags, and a saved web page or article comes back as a screenshot. To use one, bring it into Tella with from and the item’s id as sourceId:

curl -X POST https://api.tella.com/v1/library \
  -H "Authorization: Bearer $TELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "pinterest",
    "sourceId": "1234567890",
    "scope": "video",
    "videoId": "vid_abc123def456"
  }'

Tella copies the image and returns the new library item. Pass its sourceId to an overlay or a layout’s media like any other image. scope defaults to private; video saves the image to the library of the video named by videoId, which needs edit access to that video. 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. A service you haven’t connected returns 503 unavailable.

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, and model picks sunburst (the default, most capable) or flare (faster). 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

Check processing

Add the source to the library

List saved media

Browse curated sound effects

Browse curated background music

Bring in images from Pinterest, Are.na and mymind

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

​Check processing

​Add the source to the library

​Capture a page or social post

​List saved media

​Browse curated sound effects

​Browse curated background music

​Bring in images from Pinterest, Are.na and mymind

​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

Check processing

Add the source to the library

Capture a page or social post

List saved media

Browse curated sound effects

Browse curated background music

Bring in images from Pinterest, Are.na and mymind

Reuse a library item

Generate media with AI

Remove a library item