---
title: "Create a new source upload (video or image)"
method: POST
path: "/v1/sources"
tags: ["Sources"]
---

# Create a new source upload (video or image)

`POST /v1/sources`

Returns a `sourceId` and a pre-signed S3 URL. PUT the file bytes to `uploadUrl`, then reference `sourceId` from clips, layouts (b-roll media), overlays, or backgrounds. Use `kind: "image"` for images (no `duration`); Tella hosts the bytes for rendering, so you never deal with raw image URLs.

## Request body

- CreateSourceRequest — Create a new source upload (video, audio, or image). Returns a pre-signed S3 URL to PUT the bytes to, plus a `sourceId` to reference from clips, layouts, overlays, backgrounds, and sound effects.
  - `duration` number — Duration in seconds. Required for `video` and `audio`; ignored for `image`.
  - `height` integer — Height in pixels. Required for `video` and `image`; omit for `audio`.
  - `kind` 'video' | 'audio' | 'image' — Source kind: `video` (default), `audio` (e.g. sound effects), or `image`.
  - `width` integer — Width in pixels. Required for `video` and `image`; omit for `audio`.

## Response `200`

OK

- CreateSourceResponse
  - `expiresAt` string, date-time, required — ISO-8601 timestamp at which `uploadUrl` stops accepting uploads.
  - `sourceId` string, required — ID of the new source.
  - `uploadUrl` string, uri, required — Pre-signed S3 URL. PUT the file bytes here (single PUT, max ~5GB). Upload the file as-is: any common container is accepted (MP4, MOV, WebM, MP3, WAV, M4A, …) — the `.mp4` in the URL path is just the storage key, not a container requirement.

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/ba2bb13928a5/schema)