This guide shows how you can use the Analyze API to generate summaries, chapters, and highlights from videos using pre-defined formats and optional prompts for customization.

Summaries are concise overviews capturing the key points, adaptable into formats like paragraphs, emails, or bullet points based on your prompt.
Chapters offer a chronological breakdown of the video, with timestamps, headlines, and summaries for each section.
Highlights list the most significant events chronologically, including timestamps and brief descriptions.

Below are some examples of how to guide the platform in generating content tailored to your needs.

Content type	Prompt example
Specify the target audience	Generate a summary suitable for a high school audience studying environmental science.
Adjust the tone	Generate a light-hearted and humorous chapter breakdown of this documentary.
Indicate length constraints	Provide a summary fit for a Twitter post under 280 characters.
Customize text format	Generate a summary in no more than 5 bullet points.
Specify the purpose	Summarize this video from a marketer’s perspective, focusing on brand mentions and product placements.

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 meet the format requirements.

Complete example

This complete example shows how to create an index, upload a video, and analyze videos to generate summaries, chapters, and highlights. 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 summaries, chapters, and highlights
37 res_summary = client.summarize(
38     video_id=task.video_id,
39     type="summary",
40     # prompt="<YOUR_PROMPT>",
41     # temperature= 0.2
42 )
43 res_chapters = client.summarize(
44     video_id=task.video_id,
45     type="chapter",
46     # prompt="<YOUR_PROMPT>",
47     # temperature= 0.2
48 )
49 res_highlights = client.summarize(
50     video_id=task.video_id,
51     type="highlight",
52     # prompt="<YOUR_PROMPT>",
53     # temperature= 0.2
54 )
55 
56 #6. Process the results
57 print(f"Summary: {res_summary.summary}")
58 for chapter in res_chapters.chapters:
59     print(
60         f"""Chapter {chapter.chapter_number},
61 start={chapter.start_sec},
62 end={chapter.end_sec}
63 Title: {chapter.chapter_title}
64 Summary: {chapter.chapter_summary}
65 """
66     )
67 for highlight in res_highlights.highlights:
68     print(
69         f"Highlight: {highlight.highlight}, start: {highlight.start_sec}, end: {highlight.end_sec}")

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 summaries, chapters, and highlights

Function call: You call the summarize method.
Parameters:

video_id: The unique identifier of the video for which you want to generate text.
type: The type of text you want to generate. It can take one of the following values: “summary”, “chapter”, or “highlight”.
(Optional) prompt: A string you can use to provide context for the summarization task. The maximum length of a prompt is 2,000 tokens. Example: “Generate chapters using casual and conversational language to match the vlogging style of the video.”
(Optional) temperature: A number that controls the randomness of the text. A higher value generates more creative text, while a lower value produces more deterministic text.

Return value: An object containing the generated content. The response type varies based on the type parameter:

When type is summary: Returns a Summary object with an id, summary text, and usage information
When type is chapter: Returns a Chapter object with an id, array of chapters, and usage information
When type is highlight: Returns a Highlight object with an id, array of highlights, and usage information

Process the results

For summaries, you can directly print the result. You must iterate over the list and print each item individually for chapters, and highlights.