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

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

For a comprehensive guide, see the Analyze videos section.

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

  Select the Copy icon next to your key.

• Ensure the TwelveLabs SDK is installed on your computer:

  PythonNode.js

  $
  pip install twelvelabs

• The videos you wish to upload must meet the following requirements:

  • Video resolution: Must be at least 360x360 and must not exceed 5184x2160.

  • Aspect ratio: Must be between 1:1 and 1:2.4, or between 2.4:1 and 1:1. For example, you can use 1:1, 4:3, 4:5, 5:4, 16:9, 9:16, or 17:9.

  • Video and audio formats: Your video files must be encoded in the video and audio formats listed on the FFmpeg Formats Documentation page. For videos in other formats, contact us at support@twelvelabs.io.

  • Duration: Must be between 4 seconds and 60 minutes (3600s). In a future release, the maximum duration will be 2 hours (7,200 seconds).

  • File size: Must not exceed 2 GB.
    If you require different options, contact us at support@twelvelabs.io.

  • Video URLs: Must be direct links to raw video files that play without user interaction or custom video players (example: https://example.com/videos/sample-video.mp4). Video hosting platforms like YouTube and cloud storage sharing links are not supported.

Starter code

You can copy and paste the code below to analyze videos and generate text based on their content. Replace the placeholders surrounded by <> with your values.

1
from twelvelabs import TwelveLabs
2
from twelvelabs.indexes import IndexesCreateRequestModelsItem
3
from twelvelabs.tasks import TasksRetrieveResponse
4
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7
index = client.indexes.create(
8
    index_name="<YOUR_INDEX_NAME>",
9
    models=[
10
        IndexesCreateRequestModelsItem(
11
            model_name="pegasus1.2", model_options=["visual", "audio"]
12
        )
13
    ]
14
)
15
print(f"Created index: id={index.id}")
16
17
task = client.tasks.create(
18
    index_id=index.id,
19
    video_url="<YOUR_VIDEO_URL>" # Or use video_file to upload a file from the local file system
20
    )
21
print(f"Created task: id={task.id}")
22
23
def on_task_update(task: TasksRetrieveResponse):
24
    print(f"  Status={task.status}")
25
26
task = client.tasks.wait_for_done(task_id=task.id, callback=on_task_update)
27
if task.status != "ready":
28
    raise RuntimeError(f"Indexing failed with status {task.status}")
29
print(
30
    f"Upload complete. The unique identifier of your video is {task.video_id}.")
31
32
gist = client.gist(video_id=task.video_id,types=["title", "topic", "hashtag"])
33
print(f"Title={gist.title}\nTopics={gist.topics}\nHashtags={gist.hashtags}")

Step-by-step guide