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 Key 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 use must meet the following requirements:

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

  • Aspect ratio: Must be one of 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.

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, video_url="<YOUR_VIDEO_URL>")
19
print(f"Created task: id={task.id}")
20
21
def on_task_update(task: TasksRetrieveResponse):
22
    print(f"  Status={task.status}")
23
24
task = client.tasks.wait_for_done(task_id=task.id, callback=on_task_update)
25
if task.status != "ready":
26
    raise RuntimeError(f"Indexing failed with status {task.status}")
27
print(
28
    f"Upload complete. The unique identifier of your video is {task.video_id}.")
29
30
gist = client.gist(video_id=task.video_id,types=["title", "topic", "hashtag"])
31
print(f"Title={gist.title}\nTopics={gist.topics}\nHashtags={gist.hashtags}")

Step-by-step guide