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) or provide a public URL (up to 4 GB). Use direct links to raw media files. The platform does not support video hosting platforms or cloud storage sharing links.
• Multipart uploads: Upload local video files up to 5 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:

  1

  If you don’t have an account, sign up for a free account.

  2

  Go to the API Keys page.

  3

  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.

  4

  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:

  PythonNode.js

  $
  pip install twelvelabs

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.

1
from twelvelabs import TwelveLabs
2
import time
3
4
client = TwelveLabs(api_key="<YOUR_API_KEY>")
5
6
# Step 1: Upload the file
7
asset = client.assets.create(method="direct", file=open("<YOUR_FILE_PATH>", "rb"))
8
print(f"Asset created: {asset.id}, Status: {asset.status}, File type: {asset.file_type}")
9
10
# Step 2: Check the status of the asset
11
while True:
12
    status = client.assets.retrieve(asset_id=asset.id).status
13
    if status == "ready":
14
        break
15
    elif status == "failed":
16
        raise Exception("Asset processing failed")
17
    print(f"Status: {status}, waiting...")
18
    time.sleep(5)
19
print("Asset ready")

Code explanation

Multipart uploads

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

Example

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

1
from twelvelabs import TwelveLabs
2
import time
3
4
client = TwelveLabs(api_key="<YOUR_API_KEY>")
5
6
# Step 1: Upload the file
7
def progress_callback(progress):
8
    print(f"Progress: {progress.percentage:.1f}% "
9
          f"({progress.completed_chunks}/{progress.total_chunks} chunks)")
10
11
result = client.multipart_upload.upload_file(
12
    "<YOUR_FILE_PATH>",
13
    progress_callback=progress_callback,
14
)
15
print(f"Asset created: {result.asset_id}")
16
17
# Step 2: Check the status of the asset
18
while True:
19
    status = client.assets.retrieve(asset_id=result.asset_id).status
20
    if status == "ready":
21
        break
22
    elif status == "failed":
23
        raise Exception("Asset processing failed")
24
    print(f"Status: {status}, waiting...")
25
    time.sleep(5)
26
print("Asset ready")

Code explanation

Next steps

• 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. Hosted on Google Colab, they allow you to run the code directly 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.
Uploading multiple files	Upload a folder of videos and images, add them to a knowledge store, and handle rate limits and partial failures.