Titles, topics, and hashtags

This guide shows how you can 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 Key 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 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, or 9:16.
    • 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.

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.

1from twelvelabs import TwelveLabs
2from twelvelabs.models.task import Task
3
4# 1. Initialize the client
5client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7# 2. Create an index
8models = [
9{
10 "name": "pegasus1.2",
11 "options": ["visual", "audio"]
12 }
13]
14index = client.index.create(name="<YOUR_INDEX_NAME>", models=models)
15print(f"Index created: id={index.id}, name={index.name}")
16
17# 3. Upload a video
18task = client.task.create(index_id=index.id, file="<YOUR_VIDEO_FILE>")
19print(f"Task id={task.id}, Video id={task.video_id}")
20
21# 4. Monitor the indexing process
22def on_task_update(task: Task):
23 print(f" Status={task.status}")
24task.wait_for_done(sleep_interval=5, callback=on_task_update)
25if task.status != "ready":
26 raise RuntimeError(f"Indexing failed with status {task.status}")
27print(f"The unique identifier of your video is {task.video_id}.")
28
29# 5. Generate title, topics, and hashtags
30gist = client.generate.gist(video_id=task.video_id, types=["title", "topic", "hashtag"])
31print(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.
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.

2

Specify the index containing your videos

Indexes help you organize and search through related videos efficiently. This example creates a new index, but you can also use an existing index by specifying its unique identifier. See the Indexes page for more details on creating an index.
Function call: You call the index.create function.
Parameters:

  • name: The name of the index.
  • models: An object specifying your model configuration. This example enables the Pegasus video understanding model and the visual and audio model options.

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

3

Upload videos

To perform any downstream tasks, you must first upload your videos, and the platform must finish processing them.
Function call: You call the task.create function. This starts a video indexing task, which is an object of type Task that tracks the status of your video upload and indexing process.
Parameters:

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

Return value: An object of type Task containing, among other information, the following fields:

  • video_id: The unique identifier of your video
  • status: The status of your video indexing task.
Note

You can also upload multiple videos in a single API call. For details, see the Cloud-to-cloud integrations page.

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.
Function call: You call the task.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.
  • callback: A callback function that the SDK executes each time it checks the status. Note that the callback function takes a parameter of type Task representig the video indexing task you’ve created in the previous step. Use it to display the status of your video indexing task.

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

5

Generate titles, topics, and hashtags

Function call: You call the generate.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. It can take one or more of the following values: ["title", "topic", "hashtag"].
    Return value: An object containing, among other information, one or more of the following fields of type string: title, topics, hashtags.
6

Process the results

This example prints the generated text to the standard output.