> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Upload content

This guide shows you how to upload video and image content to the platform as an asset. The platform supports the following upload methods:

* **Direct uploads**: Upload local files (up to 200 MB for video and audio, 32 MB for images) or provide a public URL (up to 4 GB). Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported.
* **Multipart uploads**: Upload local videos up to 10 GB. Use multipart uploads for automatic retries, progress tracking, and improved reliability.

# Key concepts

* **Asset**: Your uploaded content. Once created, you can reference the same asset across multiple operations without uploading the file again.

# Prerequisites

* To use the platform, you need an API key:

  If you don't have an account, [sign up](https://playground.twelvelabs.io/) for a free account.

  Go to the [API Keys](https://playground.twelvelabs.io/dashboard/api-keys) page.

  If you need to create a new key, select the **Create API Key** button. Enter a name and set the expiration period. The default is 12 months.

  Select the **Copy** icon next to your key to copy it to your clipboard.

* Depending on the programming language you are using, install the TwelveLabs SDK by entering one of the following commands:

  **`Python`**

  ```shell Python
  pip install --upgrade twelvelabs
  ```

  **`Node.js`**

  ```shell Node.js
  yarn add twelvelabs-js@latest # or npm install twelvelabs-js@latest
  ```

# Direct uploads

Direct uploads create an asset from a local file or a publicly accessible URL in a single request.

## Example

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

#### Local file

**`Python`**

```python Python maxlines=22
from twelvelabs import TwelveLabs
import time

client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Step 1: Upload the file
asset = client.assets.create(method="direct", file=open("<YOUR_FILE_PATH>", "rb"))
print(f"Asset created: {asset.id}, Status: {asset.status}, File type: {asset.file_type}")

# Step 2: Check the status of the asset
while True:
    status = client.assets.retrieve(asset_id=asset.id).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Asset processing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(5)
print("Asset ready")
```

**`Node.js`**

```javascript Node.js maxlines=22
import { TwelveLabs } from "twelvelabs-js";
import fs from "fs";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Step 1: Upload the file
const asset = await client.assets.create({
  method: "direct",
  file: fs.createReadStream("<YOUR_FILE_PATH>"),
});
console.log(`Asset created: ${asset.id}, Status: ${asset.status}, File type: ${asset.fileType}`);

// Step 2: Check the status of the asset
while (true) {
  const { status } = await client.assets.retrieve(asset.id);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Asset processing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
}
console.log("Asset ready");
```

#### URL

**`Python`**

```python Python maxlines=22
from twelvelabs import TwelveLabs
import time

client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Step 1: Upload from a URL
asset = client.assets.create(method="url", url="<YOUR_MEDIA_URL>")  # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
print(f"Asset created: {asset.id}, Status: {asset.status}, File type: {asset.file_type}")

# Step 2: Check the status of the asset
while True:
    status = client.assets.retrieve(asset_id=asset.id).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Asset processing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(5)
print("Asset ready")
```

**`Node.js`**

```javascript Node.js maxlines=22
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Step 1: Upload from a URL
const asset = await client.assets.create({ method: "url", url: "<YOUR_MEDIA_URL>" }); // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
console.log(`Asset created: ${asset.id}, Status: ${asset.status}, File type: ${asset.fileType}`);

// Step 2: Check the status of the asset
while (true) {
  const { status } = await client.assets.retrieve(asset.id);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Asset processing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
}
console.log("Asset ready");
```

## Code explanation

#### Python

#### Upload the file

Upload a video or an image from a local file or a publicly accessible URL to create an asset. This example prints the asset identifier, status, and file type to the standard output.

#### Local file

**Function call**: You call the [`assets.create`](/v1.3/sdk-reference/python/upload-content/direct-uploads#create-an-asset) method.\

**Parameters**:

* `method`: The upload method. Set to `direct` for a local file.
* `file`: The local file to upload, opened in binary read mode. Maximum size: 200 MB for video and audio, 32 MB for images.\


**Return value**: An object of type `Asset` containing, among other information, a field named `id` representing the unique identifier of the newly created asset, a field named `status` representing its current state, and a field named `file_type` containing the MIME type the platform detected, such as `video/mp4` or `image/jpeg`.

#### URL

**Function call**: You call the [`assets.create`](/v1.3/sdk-reference/python/upload-content/direct-uploads#create-an-asset) method.\

**Parameters**:

* `method`: The upload method. Set to `url` for a publicly accessible URL.
* `url`: The publicly accessible URL of the media file. Maximum size: 4 GB.\


**Return value**: An object of type `Asset` containing, among other information, a field named `id` representing the unique identifier of the newly created asset, a field named `status` representing its current state, and a field named `file_type` containing the MIME type the platform detected, such as `video/mp4` or `image/jpeg`.

#### Check the status of the asset

Poll the asset until it reaches the `ready` status. This example checks every 5 seconds. An asset must reach `ready` before you can add it to a knowledge store.\

**Function call**: You call the [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) method.\

**Parameters**:

* `asset_id`: The unique identifier of the asset, from the previous step.\


**Return value**: An object of type `Asset`. Check the `status` field for the current state. The possible values are `processing`, `ready`, and `failed`.

#### Node.js

#### Upload the file

Upload a video or an image from a local file or a publicly accessible URL to create an asset. This example prints the asset identifier, status, and file type to the standard output.

#### Local file

**Function call**: You call the [`assets.create`](/v1.3/sdk-reference/node-js/upload-content/direct-uploads#create-an-asset) method.\

**Parameters**: You pass all parameters as properties of a single object.

* `method`: The upload method. Set to `direct` for a local file.
* `file`: The local file to upload. Pass a `fs.ReadStream` using `fs.createReadStream("<YOUR_FILE_PATH>")`. Maximum size: 200 MB for video and audio, 32 MB for images.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `Asset` containing, among other information, a field named `id` representing the unique identifier of the newly created asset, a field named `status` representing its current state, and a field named `fileType` containing the MIME type the platform detected, such as `video/mp4` or `image/jpeg`.

#### URL

**Function call**: You call the [`assets.create`](/v1.3/sdk-reference/node-js/upload-content/direct-uploads#create-an-asset) method.\

**Parameters**: You pass all parameters as properties of a single object.

* `method`: The upload method. Set to `url` for a publicly accessible URL.
* `url`: The publicly accessible URL of the media file. Maximum size: 4 GB.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `Asset` containing, among other information, a field named `id` representing the unique identifier of the newly created asset, a field named `status` representing its current state, and a field named `fileType` containing the MIME type the platform detected, such as `video/mp4` or `image/jpeg`.

#### Check the status of the asset

Poll the asset until it reaches the `ready` status. This example checks every 5 seconds. An asset must reach `ready` before you can add it to a knowledge store.\

**Function call**: You call the [`assets.retrieve`](/v1.3/sdk-reference/node-js/manage-assets#retrieve-an-asset) method.\

**Parameters**: You pass the asset identifier as the argument.

* `assetId`: The unique identifier of the asset, from the previous step.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `Asset`. Check the `status` field for the current state. The possible values are `processing`, `ready`, and `failed`.

# Multipart uploads

Use multipart uploads for local files larger than 200 MB, up to 10 GB.

## Example

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```python Python maxlines=25
from twelvelabs import TwelveLabs
import time

client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Step 1: Upload the file
def progress_callback(progress):
    print(f"Progress: {progress.percentage:.1f}% "
          f"({progress.completed_chunks}/{progress.total_chunks} chunks)")

result = client.multipart_upload.upload_file(
    "<YOUR_FILE_PATH>",
    progress_callback=progress_callback,
)
print(f"Asset created: {result.asset_id}")

# Step 2: Check the status of the asset
while True:
    status = client.assets.retrieve(asset_id=result.asset_id).status
    if status == "ready":
        break
    elif status == "failed":
        raise Exception("Asset processing failed")
    print(f"Status: {status}, waiting...")
    time.sleep(5)
print("Asset ready")
```

**`Node.js`**

```javascript Node.js maxlines=25
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Step 1: Upload the file
const progressCallback = (progress) => {
  console.log(
    `Progress: ${progress.percentage.toFixed(1)}% ` +
      `(${progress.completedChunks}/${progress.totalChunks} chunks)`
  );
};

const result = await client.multipartUpload.uploadFile("<YOUR_FILE_PATH>", {
  progressCallback,
});
console.log(`Asset created: ${result.assetId}`);

// Step 2: Check the status of the asset
while (true) {
  const { status } = await client.assets.retrieve(result.assetId);
  if (status === "ready") break;
  if (status === "failed") throw new Error("Asset processing failed");
  console.log(`Status: ${status}, waiting...`);
  await new Promise((r) => setTimeout(r, 5000));
}
console.log("Asset ready");
```

## Code explanation

#### Python

#### Upload the file

Upload a local file to create an asset. The SDK sets up the upload session, splits the file into chunks, uploads them in parallel with automatic retries, and reports completion. This example prints the progress and the asset identifier to the standard output.\

**Function call**: You call the [`multipart_upload.upload_file`](/v1.3/sdk-reference/python/upload-content/multipart-uploads#upload-a-file) method.\

**Parameters**:

* `file_path`: The path to the local file to upload. Maximum size: 10 GB.
* *(Optional)* `progress_callback`: A function the SDK calls with progress updates during the upload.\


**Return value**: An object of type `UploadResult` with a field named `asset_id` representing the unique identifier of the asset. For lower-level control over the individual steps, see the [Multipart uploads API reference](/v1.3/api-reference/upload-content/multipart-uploads).

#### Check the status of the asset

Poll the asset until it reaches the `ready` status. This example checks every 5 seconds. An asset must reach `ready` before you can add it to a knowledge store.\

**Function call**: You call the [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) method.\

**Parameters**:

* `asset_id`: The unique identifier of the asset, from the previous step.\


**Return value**: An object of type `Asset`. Check the `status` field for the current state. The possible values are `processing`, `ready`, and `failed`.

#### Node.js

#### Upload the file

Upload a local file to create an asset. The SDK sets up the upload session, splits the file into chunks, uploads them in parallel with automatic retries, and reports completion. This example prints the progress and the asset identifier to the standard output.\

**Function call**: You call the [`multipartUpload.uploadFile`](/v1.3/sdk-reference/node-js/upload-content/multipart-uploads#upload-a-file) method.\

**Parameters**: You pass the file path as the first argument and the options as properties of a second object.

* `filePath`: The path to the local file to upload. Maximum size: 10 GB.
* *(Optional)* `progressCallback`: A function the SDK calls with progress updates during the upload.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `UploadResult` with a field named `assetId` representing the unique identifier of the asset. For lower-level control over the individual steps, see the [Multipart uploads API reference](/v1.3/api-reference/upload-content/multipart-uploads).

#### Check the status of the asset

Poll the asset until it reaches the `ready` status. This example checks every 5 seconds. An asset must reach `ready` before you can add it to a knowledge store.\

**Function call**: You call the [`assets.retrieve`](/v1.3/sdk-reference/node-js/manage-assets#retrieve-an-asset) method.\

**Parameters**: You pass the asset identifier as the argument.

* `assetId`: The unique identifier of the asset, from the previous step.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `Asset`. Check the `status` field for the current state. The possible values are `processing`, `ready`, and `failed`.

# Next steps

* [Create a knowledge store](/v1.3/agents/guides/create-a-knowledge-store) - create a knowledge store to hold your videos and images and enable querying

# Jupyter notebooks

The notebooks below provide complete, executable code. Run the code directly on Google Colab and adapt it to your own content.

| Notebook                 | Description                                                                                                       | Try it                                                                                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Uploading content        | Upload a single video or image, wait for processing, and generate an HLS playlist or thumbnails.                  | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/guides/uploading_content.ipynb)        |
| Uploading multiple files | Upload a folder of videos and images, add them to a knowledge store, and handle rate limits and partial failures. | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/guides/uploading_multiple_files.ipynb) |