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

# Sources

> Upload video, audio, and image files for your videos, or a 3D .cube LUT to color-grade clips.

A source is an uploaded video, audio, or image file that you can use in a video as a clip, B-roll, overlay, background, music, or sound effect. You can also upload a 3D `.cube` LUT to color-grade clips. Create a source, upload the bytes to the returned pre-signed URL, then reference the `sourceId` from `create_video`, `upload_clip`, `add_layout` / `update_layout`, `add_overlay`, `update_clip`, `set_background_music`, or `add_sound_effect`.

## create\_source

Create a new source upload. Returns a `sourceId` and a pre-signed `uploadUrl` — `PUT` the file bytes to `uploadUrl` (the URL expires after 1 hour).

Once uploaded, the `sourceId` is accepted by:

| Tool | Source kind | Used as |
| - | - | - |
| `create_video` | video | The first clip of a new video |
| `upload_clip` | video | A new clip |
| `add_layout` / `update_layout` | video, image | B-roll media |
| `add_overlay` | video, image | An overlay |
| `update_clip` | video, image | The clip background |
| `set_background_music` | audio | The music track |
| `add_sound_effect` | audio | A sound effect |
| `add_library_item` | lut | Save a LUT; use the returned item `id` with `set_clip_filters` |

Upload the file as-is: any common container is accepted (MP4, MOV, WebM, MP3, WAV, M4A, …). The `.mp4` in the upload URL is just the storage key, not a container requirement — there's no need to remux or re-encode before uploading.

For audio files, set `kind: "audio"` with the audio's duration and omit `width` / `height`.

For images, set `kind: "image"` and omit `duration`. Tella hosts the uploaded image for rendering — you never deal with raw image URLs.

For a 3D `.cube` LUT, set `kind: "lut"` and omit `width`, `height`, and `duration`. Upload the file unchanged, then save it with `add_library_item`. Pass the returned library item `id`, not the `sourceId`, to [set\_clip\_filters](/docs/mcp-tools/clips#set_clip_filters).

<ParamField path="kind" type="enum<string>">
  Source kind — `video` (default), `audio`, `image`, or `lut`
</ParamField>

<ParamField path="width" type="integer">
  Width in pixels — required for `video` and `image`, omit for `audio` and `lut`
</ParamField>

<ParamField path="height" type="integer">
  Height in pixels — required for `video` and `image`, omit for `audio` and `lut`
</ParamField>

<ParamField path="duration" type="number">
  Duration in seconds — required for `video` and `audio`, omit for `image` and `lut`
</ParamField>

## get\_source

Get a source's processing status by its `sourceId`, however it was placed. After placing a newly uploaded video or audio source, poll this every few seconds until it is `ready`: while it is still processing, frames and previews of videos that use it answer not-ready instead of rendering.

| Status | Meaning |
| - | - |
| `pending` | Not placed yet. Conversion starts once one of the tools above references the source. |
| `processing` | Still uploading or converting. |
| `ready` | Usable everywhere. |
| `failed` | Conversion failed or the recording was cancelled. Upload the file again as a new source. |

<ParamField path="sourceId" type="string" required>
  Source ID from `create_source`
</ParamField>


## Related topics

- [Add a source to the library](/docs/api-reference/library/add-a-source-to-the-library.md)
- [List sources for a clip](/docs/api-reference/clips/list-sources-for-a-clip.md)
- [Get a source's processing status](/docs/api-reference/sources/get-a-sources-processing-status.md)
- [Add a clip from an uploaded source](/docs/api-reference/clips/add-a-clip-from-an-uploaded-source.md)
- [Get a thumbnail of a source on no clip](/docs/api-reference/sources/get-a-thumbnail-of-a-source-on-no-clip.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.