> ## Documentation Index
> Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Media library API

> Upload reusable media, browse Tella's curated sound effects, and reuse both across your videos.

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:

1. Create a source with `POST /v1/sources`.
2. Upload the file bytes to the returned `uploadUrl` before it expires.
3. 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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

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

## List saved media

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

```bash theme={null}
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.

<Note>
  `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.
</Note>

## Browse curated sound effects

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

```bash theme={null}
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:

```bash theme={null}
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.

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

## 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.

<Tip>
  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.
</Tip>

## Remove a library item

Pass both the library item ID and its scope:

```bash theme={null}
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.

<Card title="Library API reference" icon="photo-film" href="/docs/api-reference/library/list-library-items">
  Review all request parameters and response fields for the library endpoints.
</Card>


## Related topics

- [Public API and webhooks](/docs/help/integrations/public-api-and-webhooks.md)
- [Product Changelog](/docs/changelog.md)
- [Add media (B-roll)](/docs/help/editing/use-media.md)
- [Remix & reuse videos and clips](/docs/help/editing/remix-and-reuse-videos-and-clips.md)
- [List library items](/docs/api-reference/library/list-library-items.md)