Analyze videos

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.

  • Depending on the programming language you are using, install the TwelveLabs SDK by entering one of the following commands:

    $pip install twelvelabs
  • Your video files must meet the format requirements.

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.

1from twelvelabs import TwelveLabs
2from twelvelabs.indexes import IndexesCreateRequestModelsItem
3from twelvelabs.tasks import TasksRetrieveResponse
4
5client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7index = 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)
15print(f"Created index: id={index.id}")
16
17task = 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 )
21print(f"Created task: id={task.id}")
22
23def on_task_update(task: TasksRetrieveResponse):
24 print(f" Status={task.status}")
25
26task = client.tasks.wait_for_done(task_id=task.id, callback=on_task_update)
27if task.status != "ready":
28 raise RuntimeError(f"Indexing failed with status {task.status}")
29print(
30 f"Upload complete. The unique identifier of your video is {task.video_id}.")
31
32gist = client.gist(video_id=task.video_id,types=["title", "topic", "hashtag"])
33print(f"Title={gist.title}\nTopics={gist.topics}\nHashtags={gist.hashtags}")

Step-by-step guide

1

Import the SDK and initialize the client

Create a client instance to interact with the TwelveLabs Video Understanding Platform.

2

Create an index

Indexes store and organize your video data, allowing you to group related videos. Create one before uploading videos. See the Indexes page for more details.

3

Upload videos

To perform any downstream tasks, you must first upload your videos, and the platform must finish indexing them.

4

Monitor the indexing process

The platform requires some time to index videos. Check the status of the video indexing task until it’s completed.

5

Generate titles, topics, and hashtags

Generate one or more of the following types of text: titles, topics, and hashtags.

6

Process the results

This example prints the generated text to the standard output.