This guide shows how you can use the Analyze API to generate the following types of text:

Titles are brief phrases that capture the main idea of a video, making it easy to understand and categorize.
Topics identify the central themes of the video for effective categorization.
Hashtags are keywords that summarize a video, enhancing its searchability on social media.

You can generate one or more types of text in a single API call.

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:

$ 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.

Complete example

This complete example shows how to create an index, upload a video, and generate a title, topics and hashtags. Ensure you 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 # 1. Initialize the client
6 client = TwelveLabs(api_key="<YOUR_API_KEY>")
7 
8 # 2. Create an index
9 index = client.indexes.create(
10     index_name="<YOUR_INDEX_NAME>",
11     models=[
12         IndexesCreateRequestModelsItem(
13             model_name="pegasus1.2", model_options=["visual", "audio"]
14         )
15     ]
16 )
17 print(f"Created index: id={index.id}")
18 
19 # 3. Upload a video
20 task = client.tasks.create(
21     index_id=index.id,
22     video_url="<YOUR_VIDEO_URL>" # Or use video_file to upload a file from the local file system
23     )
24 print(f"Created task: id={task.id}")
25 
26 # 4. Monitor the indexing process
27 def on_task_update(task: TasksRetrieveResponse):
28     print(f"  Status={task.status}")
29 
30 task = client.tasks.wait_for_done(sleep_interval= 5, task_id=task.id, callback=on_task_update)
31 if task.status != "ready":
32     raise RuntimeError(f"Indexing failed with status {task.status}")
33 print(
34     f"Upload complete. The unique identifier of your video is {task.video_id}.")
35 
36 # 5. Generate title, topics, and hashtags
37 gist = client.gist(video_id=task.video_id,types=["title", "topic", "hashtag"])
38 
39 # 6. Process the results
40 print(f"Title={gist.title}\nTopics={gist.topics}\nHashtags={gist.hashtags}")

Step-by-step guide

Python

Node.js

Import the SDK and initialize the client

Create a client instance to interact with the TwelveLabs Video Understanding Platform.
Function call: You call the constructor of the TwelveLabs class.
Parameters:

api_key: The API key to authenticate your requests to the platform.

Return value: An object of type TwelveLabs configured for making API calls.

Create an index

Indexes store and organize your video data, allowing you to group related videos. Create one before uploading videos.
Function call: You call the indexes.create function.

Parameters:

index_name: The name of the index.
models: An array specifying your model configuration.

See the Indexes page for more details on creating an index and specifying the model configuration.

Return value: An object containing, among other information, a field named id representing the unique identifier of the newly created index.

Upload videos

To perform any downstream tasks, you must first upload your videos, and the platform must finish indexing them.
Function call: You call the tasks.create function.
Parameters:

index_id: The unique identifier of your index.
video_url or video_file: The publicly accessible URL or the path of your video file.

Return value: An object of type TasksCreateResponse that you can use to track the status of your video upload and indexing process. This object contains, among other information, the following fields:

id: The unique identifier of your video indexing task.
video_id: The unique identifier of your video.

Monitor the indexing process

The platform requires some time to index videos. Check the status of the video indexing task until it’s completed.
Function call: You call the tasks.wait_for_done function.
Parameters:

sleep_interval: The time interval, in seconds, between successive status checks. In this example, the method checks the status every five seconds.
task_id: The unique identifier of your video indexing task.
callback: A callback function that the SDK executes each time it checks the status.

Return value: An object of type TasksRetrieveResponse containing, among other information, a field named status representing the status of your task. Wait until the value of this field is ready.

Generate titles, topics, and hashtags

Function call: You call the gist method.
Parameters:

video_id: The unique identifier of the video for which you want to generate text.
types: An array of strings representing the types of text you want to generate. This example uses ["title", "topic", "hashtag"].

Return value: An object containing, among other information, one or more of the following fields of type string: title, topics, hashtags.

Process the results

This example prints the generated text to the standard output.