Use the /summarize endpoint if you want to utilize pre-defined formats for general summarization tasks and, optionally, provide a prompt to customize the output. This endpoint generates the following:

• Summaries: The platform returns a brief that encapsulates the key points of a video, presenting the most important information clearly and concisely. Depending on your prompt, a summary can take various forms, such as a single paragraph, a series of paragraphs, an email, or a structured list of bullet points. For example, a summary highlighting Black Friday events might include a description of a crowded mall, key commentary by a news reporter on consumer behavior, and individual perspectives on societal values associated with consumption.
• Chapters: The platform returns a chronological list of all the chapters in a video, providing a granular breakdown of its content. For each chapter, the platform returns its starting and end times, measured in seconds from the beginning of the video, a descriptive headline that offers a brief of the events or activities within that chapter, and an accompanying summary that elaborates on the headline. For example, the first chapter of a stand-up comedy might describe the comedian’s entrance and the first joke. The accompanying summary could delve into the content, detailing the comedian’s humorous take on a specific subject, such as the cultural nuances of Tai Chi exercises.
• Highlights: The platform returns a chronologically ordered list of the most important events within a video. Unlike chapters, highlights only capture the key moments, providing a snapshot of the video’s main topics. For each highlight, the platform returns its starting and end times, measured in seconds from the beginning of the video, and a brief that captures its essence. For example, a highlight might capture a significant event like a bank heist in a video with multiple scenes.

Below are some ways in which you can guide the platform to generate content tailored to your specific needs:

For a description of each field in the request and response, see the API Reference > Generate summaries, chapters, or highlights section.

Prerequisites

The examples in this guide assume the following:

• You’re familiar with the concepts that are described on the Platform overview page.
• You’ve already created an index and the Pegasus video understanding engine is enabled for this index.
• You’ve uploaded a video, and the platform has finished indexing it.

Generate a summary

To generate a summary based on the content of a video, invoke the summarize method of the generate object with the following parameters:

• video_id: A string representing the unique identifier of the video for which you want to generate a title.
• type: A string representing the type of text you want to generate. This example uses summary.

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
  video_id="<YOUR_VIDEO_ID>",
7
  type="summary"
8
)
9
print(f"Summary= {res.summary}")

The output should look similar to the following one:

Summary: The video begins with a woman discussing her recent lifestyle changes,
including her graduation from college and moving back home. She decides to vlog
a summer day in her house in Minnesota, showing viewers where she grew up. She talks
about her love for sunbathing, applying her tanning oil, and enjoying the outdoor
environment. Afterward, she shares her outfit including her favorite tank from Hollister 
and fold-over pants.\n She journeys to the Mall of America, making a pit stop at Starbucks.
At the mall, she shops at her favorite stores, including Hollister, Aritzia, and Victoria's Secret.
She purchases various items including a dainty blue floral top, gray yoga pants, and new
bras and shares her shopping haul with the viewers. The woman enjoys a sandwich, revealing
her love for the food.\n There's a quick transition to her preparing dinner at home.
She decides to whip up a tomato pasta dish called panzanella, using her mother's recipe.
After letting it marinate for a bit, she samples the mix, recalling its deliciousness from
her memories. \n In the evening, she meets her best friend Rachel for an outdoor adventure.
They go pennyboarding, a favored activity of theirs, which they usually do in certain mall
parking lots. She continues her activities with her friend, expressing her frustrations
over her troublesome skateboard. The video concludes with the woman sharing her day.

Optionally, you can use the prompt parameter to provide context for the summarization task. The following example specifies the purpose and the desired length:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
  video_id="<YOUR_VIDEO_ID>",
7
  type="summary",
8
  prompt="Generate a summary of this video for a social media post, up to two sentences.")
9
print(f"Summary= {res.summary}")

The output should look similar to the following one:

Summary: Two women share a day in their lives, discussing topics such as graduation, moving home, 
shopping hauls, cooking, and outdoor adventures. They showcase their favorite clothing items, 
prepare food, and go pennyboarding together.

Generate chapters

To generate a list of chapters based on the content of a video, invoke the summarize method of the generate object with the following parameters:

• video_id: A string representing the unique identifier of the video for which you want to generate a title.
• type: A string representing the type of text you want to generate. This example uses chapter.

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
    video_id="<YOUR_VIDEO_ID>",
7
    type="chapter",
8
)
9
for chapter in res.chapters:
10
    print(
11
        f"""Chapter {chapter.chapter_number},
12
start={chapter.start},
13
end={chapter.end}
14
Title: {chapter.chapter_title}
15
Summary: {chapter.chapter_summary}
16
"""
17
    )

The output should look similar to the following one:

Chapter 0,
start=0,
end=90
Title: College graduation and temporary move back home
Summary: A woman discusses her recent college graduation and temporary move back home.
Chapter 1,
start=90,
end=210
Title: Enjoying a summer day in Minnesota
Summary: The woman vlogs about her summer day, sharing her experience while standing in her 
childhood home in Minnesota. She talks about her love for getting some sun and shows the camera 
around her house.
Chapter 2,
start=210,
end=300
Title: Shopping at the Mall of America
Summary: The woman explores the Mall of America, mentioning her favorite stores and sharing her 
shopping haul.
Chapter 3,
start=300,
end=360
Title: Sharing favorite clothing items
Summary: The woman showcases her favorite clothing items, discussing her new yoga pants and tops 
from Aritzia and Victoria's Secret.
Chapter 4,
start=360,
end=480
Title: Food preparation and outdoor activities
Summary: The woman demonstrates how to make a bread salad and later meets up with her friend Rachel 
to go pennyboarding at a parking garage.

The following example uses the prompt parameter to indicate that the tone of voice should be casual and conversational, matching the vlogging style of the video:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
    video_id="<YOUR_VIDEO_ID>",
7
    type="chapter",
8
    prompt="Generate chapters using casual and conversational language to match the vlogging style of the video."
9
)
10
for chapter in res.chapters:
11
    print(
12
        f"""Chapter {chapter.chapter_number},
13
start={chapter.start},
14
end={chapter.end}
15
Title: {chapter.chapter_title}
16
Summary: {chapter.chapter_summary}
17
"""
18
    )

Generate highlights

To generate a list of the important events or activities within a video, invoke the summarize method of the generate object with the following parameters:

• video_id: A string representing the unique identifier of the video for which you want to generate a title.
• type: A string representing the type of text you want to generate. This example uses highlight.

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
    video_id="<YOUR_VIDEO_ID>",
7
    type="highlight"
8
)
9
for highlight in res.highlights:
10
    print(f"Highlight: {highlight.highlight}, start: {highlight.start}, end: {highlight.end}")

The output should be similar to the following one:

Highlight: A woman vlogs about her summer day, sharing her experience while standing in her 
childhood home in Minnesota., start: 30, end: 60
Highlight: The woman talks about the heat and her confusion regarding sweat and tanning oil. 
She also mentions her outfit, consisting of a tank top and fold-over pants., start: 150, end: 180
Highlight: A woman is making a video of her food preparation and tasting., start: 420, end: 450

The following example uses the prompt parameter to generate highlights for the same video, showcasing the most entertaining parts:

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
res = client.generate.summarize(
6
    video_id="<YOUR_VIDEO_ID>",
7
    type="highlight",
8
    prompt="Generate highlights that showcase the most entertaining parts of the video."
9
)
10
for highlight in res.highlights:
11
    print(f"Highlight: {highlight.highlight}, start: {highlight.start}, end: {highlight.end}")

The output should look similar to the following one:

Highlight: The woman discovers a foul smell in her car while vlogging about her day., 
start: 120, end: 150
Highlight: The woman shares her experience of shopping in a mall and discusses a surprising 
incident that happened to her., start: 210, end: 240