This quickstart guide provides a simplified introduction to analyzing videos to generate text using the TwelveLabs Video Understanding Platform. It includes the following:

• A basic working example
• Minimal implementation details
• Core parameters for common use cases

For a comprehensive guide, see the Analyze videos section.

Key concepts

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

• Index: A container that organizes your video content
• Asset: Your uploaded file
• Indexed asset: A video that has been indexed and is ready for downstream tasks

Workflow

Upload and index your videos before you analyze them. The platform indexes videos asynchronously. After indexing completes, you can analyze your videos using custom prompts to generate summaries, extract insights, answer content-related questions, or create structured responses tailored to your specific requirements.

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

• Your video files must meet the following requirements:

  • For this guide: Files up to 4 GB when using publicly accessible URLs or 200 MB for local files
  • Model capabilities: See the complete requirements for resolution, aspect ratio, and supported formats.

  For other upload methods with different limits, see the Upload methods page.

Starter code

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

1
import time
2
from twelvelabs import TwelveLabs
3
4
# 1. Initialize the client
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7
# 2. Create an index
8
# An index is a container for organizing your video content
9
index = client.indexes.create(
10
    index_name="<YOUR_INDEX_NAME>",
11
    models=[{"model_name": "pegasus1.2", "model_options": ["visual", "audio"]}]
12
)
13
print(f"Created index: id={index.id}")
14
15
# 3. Upload a video
16
asset = client.assets.create(
17
    method="url",
18
    url="<YOUR_VIDEO_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
19
    # Or use method="direct" and file=open("<PATH_TO_VIDEO_FILE>", "rb") to upload a file from the local file system
20
)
21
print(f"Created asset: id={asset.id}")
22
23
# 4. Index your video
24
indexed_asset = client.indexes.indexed_assets.create(
25
    index_id=index.id,
26
    asset_id=asset.id
27
)
28
print(f"Created indexed asset: id={indexed_asset.id}")
29
30
# 5. Monitor the indexing process
31
print("Waiting for indexing to complete.")
32
while True:
33
    indexed_asset = client.indexes.indexed_assets.retrieve(
34
        index.id,
35
        indexed_asset.id
36
    )
37
    print(f"  Status={indexed_asset.status}")
38
39
    if indexed_asset.status == "ready":
40
        print("Indexing complete!")
41
        break
42
    elif indexed_asset.status == "failed":
43
        raise RuntimeError("Indexing failed")
44
45
    time.sleep(5)
46
47
# 6. Analyze your video
48
text_stream = client.analyze_stream(video_id=indexed_asset.id, prompt="<YOUR_PROMPT>")
49
50
# 7. Process the results
51
for text in text_stream:
52
    if text.event_type == "text_generation":
53
        print(text.text)

Code explanation