This guide shows how to upload videos and images, build a knowledge store, and generate an overview of your content. You can also extract and track entities, search your content, and organize it by theme.

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, generate a response from the knowledge store.

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. Adapt the query to match your content and what you want to learn from it.

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: Generate a response
48
response = client.responses.create(
49
    knowledge_store_id=store.id,
50
    input=[{"type": "message", "role": "user", "content": "Give me an overview of this content - main themes, key subjects, and any patterns."}],
51
)
52
for output in response.output:
53
    if output.type == "message":
54
        for content in output.content:
55
            print(content.text)

Code explanation

Next steps

• Create a response - the complete guide: generate responses from a knowledge store, customize Jockey’s behavior with instructions, and inspect its intermediate outputs
• Streaming - receive tokens in real time instead of waiting for the full response
• Structured output - receive typed JSON by providing a schema
• Multi-turn sessions - maintain conversation context across requests