The TwelveLabs Node.js SDK provides methods to analyze videos to generate text from their content.

Titles, topics, and hashtags

This method method has been flattened and is now called client.gist instead of client.generate.gist. The client.generate.gist method will remain available until July 30, 2025; after this date, it will be deprecated. Update your code to use client.gist to ensure uninterrupted service.

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 async gist(
2   request: TwelvelabsApi.GistRequest,
3   requestOptions?: TwelvelabsApiClient.RequestOptions
4 ): core.HttpResponsePromise<TwelvelabsApi.Gist>

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.GistRequest`	Yes	The request object containing the video ID and gist types.
`requestOptions`	`TwelvelabsApiClient.RequestOptions`	No	Request-specific configuration.

The GistRequest interface contains the following properties:

Name	Type	Required	Description
`videoId`	`string`	Yes	The unique identifier of the video for which you want to generate text.
`types`	`TwelvelabsApi.GistRequestTypesItem[]`	Yes	The types of text you want to generate. Available values: `"title"`, `"topic"`, `"hashtag"`.

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.Gist instance.

The Gist interface contains the following properties:

Name	Type	Description
`id`	`string`	Unique identifier of the response.
`title`	`string`	Suggested title for the video.
`topics`	`string[]`	An array of topics that are relevant to the video.
`hashtags`	`string[]`	An array of hashtags that are relevant to the video.
`usage`	`TokenUsage`	The number of tokens used in the generation.

The TokenUsage interface contains the following properties:

Name	Type	Description
`outputTokens`	`number`	The number of tokens in the generated text.

API Reference: Titles, topics, and hashtags page.

Related guide: Titles, topics, and hashtags.

Summaries, chapters, and highlights

This method method has been flattened and is now called client.summarize instead of client.generate.summarize. The client.generate.summarize method will remain available until July 30, 2025; after this date, it will be deprecated. Update your code to use client.summarize to ensure uninterrupted service.

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 summarize(
2   request: TwelvelabsApi.SummarizeRequest,
3   requestOptions?: TwelvelabsApiClient.RequestOptions
4 ): core.HttpResponsePromise<TwelvelabsApi.SummarizeResponse>;

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.SummarizeRequest`	Yes	Specifies the type of text you wish to generate.
`request_options`	`TwelvelabsApiClient.RequestOptions`	No	Request-specific configuration.

The SummarizeRequest interface contains the following properties:

Name	Type	Required	Description
`videoId`	`string`	Yes	The unique identifier of the video that you want to summarize.
`type`	`string`	Yes	Specifies the type of text. Use `summary` for a brief report, `chapter` for a chronological list of chapters, or `highlight` for key moments.
`prompt`	`string`	No	Use this field to provide context for the summarization task, such as the target audience, style, tone of voice, and purpose. Maximum length is 2,000 tokens.
`temperature`	`number`	No	Controls the randomness of the text output. A higher value generates more creative text, while a lower value produces more deterministic text. Default: 0.2, Min: 0, Max: 1.
`requestOptions`	[`RequestOptions`]	No	Request-specific configuration.

Return value: Returns a Promise that resolves to 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:

Name	Type	Description
`summarizeType`	`"summary"`	Indicates this is a summary response.
`id`	`string`	Unique identifier of the response.
`summary`	`string`	A brief report of the main points of the video.
`usage`	`TokenUsage`	The number of tokens used in the generation.

When type is "chapter" - Returns a SummarizeResponse.Chapter object with the following properties:

Name	Type	Description
`summarizeType`	`"chapter"`	Indicates this is a chapter response.
`id`	`string`	Unique identifier of the response.
`chapters`	`SummarizeChapterResultChaptersItem[]`	An array that contains details about the detected chapters and their content.
`usage`	`TokenUsage`	The number of tokens used in the generation.

When type is "highlight" - Returns a SummarizeResponse.Highlight object with the following properties:

Name	Type	Description
`summarizeType`	`"highlight"`	Indicates this is a highlight response.
`id`	`string`	Unique identifier of the response.
`highlights`	`SummarizeHighlightResultHighlightsItem[]`	An array that contains the highlights.
`usage`	`TokenUsage`	The number of tokens used in the generation.

The SummarizeChapterResultChaptersItem interface contains the following properties:

Name	Type	Description
`chapterNumber`	`number`	The sequence number of the chapter. Note that this field starts at 0.
`startSec`	`number`	The starting time of the chapter, measured in seconds from the beginning of the video.
`endSec`	`number`	The ending time of the chapter, measured in seconds from the beginning of the video.
`chapterTitle`	`string`	The title of the chapter.
`chapterSummary`	`string`	A brief summary describing the content of the chapter.

The SummarizeHighlightResultHighlightsItem interface contains the following properties:

Name	Type	Description
`startSec`	`number`	The starting time of the highlight, measured in seconds from the beginning of the video.
`endSec`	`number`	The ending time of the highlight, measured in seconds from the beginning of the video.
`highlight`	`string`	The title of the highlight.
`highlightSummary`	`string`	A brief description that captures the essence of this part of the video.

The TokenUsage interface contains the following properties:

Name	Type	Description
`outputTokens`	`number`	The number of tokens in the generated text.

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 analyze(request: TwelvelabsApi.AnalyzeRequest, requestOptions?: TwelvelabsApiClient.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.NonStreamAnalyzeResponse>;

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.AnalyzeRequest`	Yes	The request object containing the parameters for performing an open-ended analysis.
`requestOptions`	`RequestOptions`	No	Request-specific configuration.

The AnalyzeRequest class contains the following properties:

Name	Type	Required	Description
`videoId`	`string`	Yes	The unique identifier of the video you wish to analyze and generate text for.
`prompt`	`string`	Yes	The prompt to customize the output. The maximum length is 2,000 tokens.
`temperature`	`number`	No	Controls the randomness of the text output. Higher values generate more creative text, while lower values produce more deterministic output. Default: 0.2, Min: 0, Max: 1.

Return value: Returns a Promise that resolves to a NonStreamAnalyzeResponse object containing the generated text.

The NonStreamAnalyzeResponse interface contains the following properties:

Name	Type	Description
`id`	`string`	Unique identifier of the response.
`data`	`string`	The generated text based on the prompt you provided.
`usage`	`TokenUsage`	The number of tokens used in the generation.

The TokenUsage interface contains the following properties:

Name	Type	Description
`outputTokens`	`number`	The number of tokens in the generated text.

API Reference: Open-ended analysis page.

Related guide: Open-ended analysis.

Open-ended analysis with streaming responses

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

Function signature and example:

1 async analyzeStream(
2   request: TwelvelabsApi.AnalyzeStreamRequest,
3   requestOptions?: TwelvelabsApiClient.RequestOptions
4 ): Promise<core.Stream<TwelvelabsApi.StreamAnalyzeResponse>>

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.AnalyzeStreamRequest`	Yes	The request object containing the parameters for performing an open-ended analysis.
`requestOptions`	[`RequestOptions`]	No	Request-specific configuration.

The AnalyzeStreamRequest class contains the following properties:

Name	Type	Required	Description
`videoId`	`string`	Yes	The unique identifier of the video you wish to analyze and generate text for.
`prompt`	`string`	Yes	The prompt to customize the output. The maximum length is 2,000 tokens.
`temperature`	`number`	No	Controls the randomness of the text output. Higher values generate more creative text, while lower values produce more deterministic output. Default: 0.2, Min: 0, Max: 1.

Return value: Returns a Promise that resolves to a Stream<StreamAnalyzeResponse> object that can be iterated over to receive streaming text chunks.

The StreamAnalyzeResponse can be either a StreamStartResponse, a StreamTextResponse, or a StreamEndResponse.

The StreamStartResponse interface contains the following properties:

Name	Type	Description
`eventType`	`string`	This field is always set to `stream_start` for this event.
`metadata`	`StreamStartResponseMetadata`	An object containing metadata about the stream.

The StreamTextResponse interface contains the following properties:

Name	Type	Description
`eventType`	`string`	This field is always set to `text_generation` for this event.
`text`	`string`	A fragment of the generated text. Note that text fragments may be split at arbitrary points, not necessarily at word or sentence boundaries.

The StreamEndResponse interface contains the following properties:

Name	Type	Description
`eventType`	`string`	This field is always set to `stream_end` for this event.
`metadata`	`StreamEndResponseMetadata`	An object containing metadata about the stream.

The StreamStartResponseMetadata interface contains the following properties:

Name	Type	Description
`generationId`	`string`	A unique identifier for the generation session.

The StreamEndResponseMetadata interface contains the following properties:

Name	Type	Description
`generationId`	`string`	The same unique identifier provided in the `stream_start` event.
`usage`	`TokenUsage`	The number of tokens used in the generation.

The TokenUsage interface contains the following properties:

Name	Type	Description
`outputTokens`	`number`	The number of tokens in the generated text.

API Reference: Open-ended analysis page.

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.