Upload content | TwelveLabs

An asset is a video file you upload to the platform. Each asset has a unique identifier that you can reference across multiple knowledge stores.

Methods

Method	Limit	Reference
Direct uploads (local file)	Up to 200 MB	Python SDK \| Node.js SDK \| API Reference
Direct uploads (public URL)	Up to 2 GB	Python SDK \| Node.js SDK \| API Reference
Multipart uploads	Up to 2 GB	Python SDK \| Node.js SDK \| API Reference

Use multipart uploads for automatic retry on failure, upload progress tracking, and better reliability, performance, and observability.

When providing a URL, use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported.

Upload a local file

Upload a local video file up to 200 MB. Set the method parameter to direct and pass the file in the file parameter.

1 import requests
2 
3 API_KEY = "<YOUR_API_KEY>"
4 BASE_URL = "https://api.twelvelabs.io/v1.3"
5 HEADERS = {"x-api-key": API_KEY}
6 
7 response = requests.post(
8     f"{BASE_URL}/assets",
9     headers=HEADERS,
10     files=[
11         ("method", (None, "direct")),
12         ("file", open("<YOUR_FILE_PATH>", "rb")),
13     ]
14 )
15 asset = response.json()
16 print(f"Asset ID: {asset['_id']}, Status: {asset['status']}")

Direct uploads under 200 MB return synchronously with status: ready.

Upload from a URL

Upload a video from a publicly accessible URL, up to 2 GB. Set the method parameter to url and pass the URL in the url parameter.

1 import requests
2 
3 API_KEY = "<YOUR_API_KEY>"
4 BASE_URL = "https://api.twelvelabs.io/v1.3"
5 HEADERS = {"x-api-key": API_KEY}
6 
7 response = requests.post(
8     f"{BASE_URL}/assets",
9     headers=HEADERS,
10     files=[
11         ("method", (None, "url")),
12         ("url", (None, "<YOUR_VIDEO_URL>")),
13     ]
14 )
15 asset = response.json()
16 print(f"Asset ID: {asset['_id']}, Status: {asset['status']}")

URL uploads over 200 MB return with status: processing. Poll the asset status until it reaches ready. See Waiting for processing below.

Multipart upload

Upload a local video file up to 2 GB. This example uses the Python SDK, which handles chunking, parallel uploads, retries, and progress tracking.

1 from twelvelabs import TwelveLabs
2 
3 client = TwelveLabs(api_key="<YOUR_API_KEY>")
4 
5 def progress_callback(progress):
6     print(f"Progress: {progress.percentage:.1f}% ({progress.completed_chunks}/{progress.total_chunks} chunks)")
7 
8 result = client.multipart_upload.upload_file(
9     "<YOUR_FILE_PATH>",
10     progress_callback=progress_callback,
11 )
12 print(f"Asset ID: {result.asset_id}")

The upload_file method returns when the upload finishes. No polling is required. For the full parameter reference, see the Python SDK or Node.js SDK documentation.

Waiting for processing

URL uploads over 200 MB return with status: processing. Poll the asset status until it reaches ready:

1 import time
2 import requests
3 
4 HEADERS = {"x-api-key": "YOUR_API_KEY"}
5 BASE_URL = "https://api.twelvelabs.io/v1.3"
6 
7 asset_id = asset["_id"]
8 while True:
9     response = requests.get(f"{BASE_URL}/assets/{asset_id}", headers=HEADERS)
10     status = response.json()["status"]
11     if status == "ready":
12         break
13     elif status == "failed":
14         raise Exception("Upload processing failed")
15     time.sleep(5)

An asset must reach ready status before you can add it to a knowledge store.

Jupyter notebook

Download the notebook to run this guide interactively.