The TwelveLabs Python SDK provides methods to analyze videos and generate text from their content.

Related quickstart notebook

Titles, topics, and hashtags

Description: This method analyzes a specific video and generates titles, topics, and hashtags based on its content. It uses predefined formats and doesn’t require a custom prompt, and it’s best for generating immediate and straightforward text representations without specific customization.

Function signature and example:

1
def gist(
2
    self,
3
    *,
4
    video_id: str,
5
    types: typing.Sequence[GistRequestTypesItem],
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> Gist

Parameters:

Return value: Returns a Gist object.

The Gist class contains the following properties:

The TokenUsage class contains the following properties:

API Reference: Generate titles, topics, and hashtags.

Related guide: Titles, topics, and hashtags.

Summaries, chapters, and highlights

Description: This method analyzes a video and generates summaries, chapters, or highlights based on its content. Optionally, you can provide a prompt to customize the output.

Function signature and example:

1
from twelvelabs import TwelveLabs
2
3
def summarize(
4
    self,
5
    *,
6
    video_id: str,
7
    type: str,
8
    prompt: typing.Optional[str] = OMIT,
9
    temperature: typing.Optional[float] = OMIT,
10
    response_format: typing.Optional[ResponseFormat] = OMIT,
11
    max_tokens: typing.Optional[int] = OMIT,
12
    request_options: typing.Optional[RequestOptions] = None,
13
) -> SummarizeResponse

Parameters:

The ResponseFormat class contains the following properties:

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

When type is "summary" - Returns a SummarizeResponse_Summary object with the following properties:

When type is "chapter" - Returns a SummarizeResponse_Chapter object with the following properties:

When type is "highlight" - Returns a SummarizeResponse_Highlight object with the following properties:

The SummarizeChapterResultChaptersItem class contains the following properties:

The SummarizeHighlightResultHighlightsItem class contains the following properties:

The TokenUsage class contains the following properties:

API Reference: Summaries, chapters, and highlights.

Related guide: Summaries, chapters, and highlights.

Open-ended analysis

Description: This method analyzes a video and generates text based on its content.

Function signature and example:

1
def analyze(
2
    self,
3
    *,
4
    video_id: str,
5
    prompt: str,
6
    temperature: typing.Optional[float] = OMIT,
7
    response_format: typing.Optional[ResponseFormat] = OMIT,
8
    max_tokens: typing.Optional[int] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> NonStreamAnalyzeResponse:

Parameters:

The ResponseFormat class contains the following properties:

Return value: Returns a NonStreamAnalyzeResponse object containing the generated text.

The NonStreamAnalyzeResponse class contains the following properties:

The TokenUsage class contains the following properties:

The maximum length of the response is 4,096 tokens.

API Reference: Open-ended analysis.

Related guide: Open-ended analysis.

Open-ended analysis with streaming responses

Description: This method analyzes a video and generates open-ended text based on its content.

Function signature and example:

1
def analyze_stream(
2
    self,
3
    *,
4
    video_id: str,
5
    prompt: str,
6
    temperature: typing.Optional[float] = OMIT,
7
    response_format: typing.Optional[ResponseFormat] = OMIT,
8
    max_tokens: typing.Optional[int] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> typing.Iterator[StreamAnalyzeResponse]

Parameters:

The ResponseFormat class contains the following properties:

Return value: Returns an iterator of StreamAnalyzeResponse objects. Each response can be a StreamAnalyzeResponse_StreamStart, StreamAnalyzeResponse_TextGeneration, or StreamAnalyzeResponse_StreamEnd.

The StreamAnalyzeResponse_StreamStart class contains the following properties:

The StreamAnalyzeResponse_TextGeneration class contains the following properties:

The StreamAnalyzeResponse_StreamEnd class contains the following properties:

The StreamStartResponseMetadata class contains the following properties:

The StreamEndResponseMetadata class contains the following properties:

The TokenUsage class contains the following properties:

The maximum length of the response is 4,096 tokens.

API Reference: Open-ended analysis.

Related guide: Open-ended analysis.

Error codes

This section lists the most common error messages you may encounter while analyzing videos.

• token_limit_exceeded
  • Your request could not be processed due to exceeding maximum token limit. Please try with another request or another video with shorter duration.
• index_not_supported_for_generate
  • You can only summarize videos uploaded to an index with an engine from the Pegasus family enabled.