> ## 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 a video, audio, or image file to use as a clip, B-roll, overlay, background, music, or sound effect.

A source is an uploaded file (video, audio, or image) that can be turned into a new video or clip, or referenced as B-roll media, an overlay, a clip background, background music, or a sound effect. 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                |

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.

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

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

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

<ParamField path="duration" type="number">
  Duration in seconds — required for `video` and `audio`, ignored for `image`
</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)
- [Add a clip from an uploaded source](/docs/api-reference/clips/add-a-clip-from-an-uploaded-source.md)
- [Get a source thumbnail or animated preview](/docs/api-reference/clips/get-a-source-thumbnail-or-animated-preview.md)
- [Get the audio waveform JSON for a source](/docs/api-reference/clips/get-the-audio-waveform-json-for-a-source.md)