This guide shows how to upload videos and images, build a knowledge store, and search it with a natural-language query. The search returns matching video clips and images ranked by relevance.

Key concepts

This section explains the key concepts and terminology used in this guide:

• Asset: Your uploaded content. Once created, you can reference the same asset across multiple operations without uploading the file again.
• Knowledge store: A persistent store of your videos and images plus the understanding the platform derives from them — spatiotemporal context, a typed ontology, and embeddings — that together enable corpus-level reasoning.
• Knowledge store item: An asset added to a knowledge store. The platform processes each item asynchronously. When processing finishes, the item is ready for downstream tasks.

Workflow

Upload your videos and images as assets, then create a knowledge store. Add the assets to the knowledge store. The platform indexes the content asynchronously. When the items reach the ready status, search the knowledge store with a natural-language query.

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

• Publicly accessible video or image URLs that point directly to media files. This quickstart demonstrates the URL upload method. For local file uploads, see the Upload content page.

• Upload limits: Public video URLs up to 4 GB, local video files up to 200 MB, or images up to 32 MB. For local files up to 5 GB, see the Upload content page.

Starter code

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

1
from twelvelabs import TwelveLabs
2
import time
3
4
# Step 1: Initialize the client
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7
# Step 2: Upload a video or an image
8
asset = client.assets.create(method="url", url="<YOUR_MEDIA_URL>")
9
print(f"Asset created: {asset.id}")
10
11
# Step 3: Check the status of the asset
12
while True:
13
    status = client.assets.retrieve(asset_id=asset.id).status
14
    if status == "ready":
15
        break
16
    elif status == "failed":
17
        raise Exception("Asset processing failed")
18
    print(f"Status: {status}, waiting...")
19
    time.sleep(5)
20
print("Asset ready")
21
22
# Step 4: Create a knowledge store
23
store = client.knowledge_stores.create(name="<YOUR_KNOWLEDGE_STORE_NAME>")
24
print(f"Knowledge store created: {store.id}")
25
26
# Step 5: Add the asset to the knowledge store
27
item = client.knowledge_store_items.create(
28
    knowledge_store_id=store.id,
29
    asset_id=asset.id,
30
    # asset_type="image",  # Uncomment if your asset is an image (the default is video)
31
)
32
print(f"Item added: {item.id}")
33
34
# Step 6: Check the status of the knowledge store item
35
while True:
36
    status = client.knowledge_store_items.retrieve(
37
        knowledge_store_id=store.id, item_id=item.id
38
    ).status
39
    if status == "ready":
40
        break
41
    elif status == "failed":
42
        raise Exception("Indexing failed")
43
    print(f"Status: {status}, waiting...")
44
    time.sleep(10)
45
print("Indexing complete")
46
47
# Step 7: Search the knowledge store
48
result = client.knowledge_stores.search(
49
    knowledge_store_id=store.id,
50
    query={"text": "<YOUR_QUERY>"},
51
    search_options={"video": {"modalities": ["visual", "audio"]}},
52
)
53
for hit in result.data:
54
    if hit.asset_type == "video":
55
        clip = hit.matches[0]
56
        print(f"Rank {hit.rank}: video {hit.item_id}  {clip.start_sec}s-{clip.end_sec}s")
57
    elif hit.asset_type == "image":
58
        print(f"Rank {hit.rank}: image {hit.item_id}")

Code explanation

Next steps

• Search a knowledge store - the complete guide: filter results, group clips, and page through large result sets