Deprecation notice

The method described on this page will be deprecated on February 15, 2026. Use structured JSON responses instead. For migration instructions, see the Release notes page.

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.

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

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 # An index is a container for organizing your video content
10 index = client.indexes.create(
11     index_name="<YOUR_INDEX_NAME>",
12     models=[
13         IndexesCreateRequestModelsItem(
14             model_name="pegasus1.2", model_options=["visual", "audio"]
15         )
16     ]
17 )
18 print(f"Created index: id={index.id}")
19 
20 # 3. Upload a video
21 task = client.tasks.create(
22     index_id=index.id,
23     video_url="<YOUR_VIDEO_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
24     # Or for a local file: video_file=open("<PATH_TO_VIDEO_FILE>", "rb")
25     )
26 print(f"Created task: id={task.id}")
27 
28 # 4. Monitor the indexing process
29 def on_task_update(task: TasksRetrieveResponse):
30     print(f"  Status={task.status}")
31 
32 task = client.tasks.wait_for_done(sleep_interval= 5, task_id=task.id, callback=on_task_update)
33 if task.status != "ready":
34     raise RuntimeError(f"Indexing failed with status {task.status}")
35 print(
36     f"Upload complete. The unique identifier of your video is {task.video_id}.")
37 
38 # 5. Generate title, topics, and hashtags
39 gist = client.gist(video_id=task.video_id,types=["title", "topic", "hashtag"])
40 
41 # 6. Process the results
42 print(f"Title={gist.title}\nTopics={gist.topics}\nHashtags={gist.hashtags}")

Code explanation

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. This guide shows how to create one, but you can also use an existing index.
Function call: You call the indexes.create function.
Parameters:

index_name: The name of the index.
models: An array specifying your model configuration. This example enables the Pegasus video understanding model and specifies that it analyzes visual and audio modalities.

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

Return value: An object of type IndexesCreateResponse containing a field named id representing the unique identifier of the newly created index.

Upload a video

Upload a video to create an asset. For details about the available upload methods and the corresponding limits, see the Upload methods page.
Function call: You call the assets.create function.
Parameters:

method: The upload method for your asset. Use url for a publicly accessible or direct to upload a local file. This example uses url.
url or file: The publicly accessible URL of your video or an opened file object in binary read mode. This example uses url.

Return value: An object of type Asset. This object contains, among other information, a field named id representing the unique identifier of your asset.

Monitor the indexing process

The platform requires some time to index videos. Check the status of the indexing process until it’s completed.
Function call: You call the indexes.indexed_assets.retrieve function.
Parameters:

index_id: The unique identifier of your video index.
indexed_asset_id: The unique identifier of your indexed asset.

Return value: An object of type IndexedAssetDetailed containing, among other information, a field named status representing the status of the indexing process. 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.