Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • TwelveLabs API
    • Introduction
    • Authentication
    • Typical workflows
  • API Reference
    • Manage indexes
    • Upload videos
    • Manage videos
    • Any-to-video search
    • Create video embeddings
    • Create text, image, and audio embeddings
    • Analyze videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceAnalyze videos

POST
https://api.twelvelabs.io/v1.3/summarize
POST
/v1.3/summarize
1curl -X POST https://api.twelvelabs.io/v1.3/summarize \
2     -H "x-api-key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "video_id": "6298d673f1090f1100476d4c",
6  "type": "summary",
7  "prompt": "Generate a summary of this video for a social media post, up to two sentences.",
8  "temperature": 0.2
9}'
Try it
200Successful
1{
2  "summarize_type": "summary",
3  "id": "56dd2567-9b34-4ee9-9fbb-c20fc283e5bf",
4  "summary": "Black Friday shoppers are shown in a mall, pushing and shoving through the crowds. A news reporter talks about shopping mania and its impact on stores. He mentions that stores are filled to the brim and that the hunt for deals can make people miserable. A woman talks to the camera about how people have lost their minds and how the American dream has become associated with material possessions.\n",
5  "usage": {
6    "output_tokens": 1
7  }
8}
Was this page helpful?
Previous

Open-ended texts

Next
Built with
This endpoint analyzes videos and generates summaries, chapters, or highlights. Optionally, you can provide a prompt to customize the output. <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>
Summaries, chapters, or highlights

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-key" target="_blank">API Key</a> page. </Note>

Request

Request to generate a summary of a video.
video_idstringRequired
The unique identifier of the video that you want to summarize.
typestringRequired
Specifies the type of summary. Use one of the following values: - `summary`: A brief that encapsulates the key points of a video, presenting the most important information clearly and concisely. - `chapter`: 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 clip, a descriptive headline that offers a brief of the events or activities within that part of the video, and an accompanying summary that elaborates on the headline. - `highlight`: 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, a title, and a brief description that captures the essence of this part of the video.
promptstringOptional
Use this field to provide context for the summarization task, such as the target audience, style, tone of voice, and purpose. <Note title="Notes"> - Your prompts can be instructive or descriptive, or you can also phrase them as questions. - The maximum length of a prompt is 2,000 tokens. </Note> **Example**: Generate a summary of this video for a social media post, up to two sentences.
temperaturedoubleOptional
Controls the randomness of the text output generated by the model. A higher value generates more creative text, while a lower value produces more deterministic text output. **Default:** 0.2 **Min:** 0 **Max:** 1
response_formatobjectOptional
Use this parameter to specify the format of the response. This parameter is only valid when the `type` parameter is set to `summary`. If you omit this parameter, the platform returns unstructured text.
max_tokensintegerOptional<=4096
The maximum number of tokens to generate.

Response

The specified video has successfully been summarized.
summaryobject
OR
chapterobject
OR
highlightobject

Errors

Your API key.

Note

You can find your API key on the API Key page.

The maximum number of tokens to generate.
The specified video has successfully been summarized.

Specifies the type of summary. Use one of the following values:

  • summary: A brief that encapsulates the key points of a video, presenting the most important information clearly and concisely.
  • chapter: 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 clip, a descriptive headline that offers a brief of the events or activities within that part of the video, and an accompanying summary that elaborates on the headline.
  • highlight: 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, a title, and a brief description that captures the essence of this part of the video.

Controls the randomness of the text output generated by the model. A higher value generates more creative text, while a lower value produces more deterministic text output.

Default: 0.2 Min: 0 Max: 1

Use this field to provide context for the summarization task, such as the target audience, style, tone of voice, and purpose.

Notes
  • Your prompts can be instructive or descriptive, or you can also phrase them as questions.
  • The maximum length of a prompt is 2,000 tokens.

Example: Generate a summary of this video for a social media post, up to two sentences.

Use this parameter to specify the format of the response. This parameter is only valid when the type parameter is set to summary. If you omit this parameter, the platform returns unstructured text.

This endpoint analyzes videos and generates summaries, chapters, or highlights. Optionally, you can provide a prompt to customize the output.

Note

This endpoint is rate-limited. For details, see the Rate limits page.

Open-ended texts