Open-ended analysis | TwelveLabs

This endpoint analyzes your videos and creates fully customizable text based on your prompts, including but not limited to tables of content, action items, memos, and detailed analyses.

Notes

This endpoint is rate-limited. For details, see the Rate limits page.
This endpoint supports streaming responses. For details on integrating this feature into your application, refer to the Open-ended analysis.

This endpoint analyzes your videos and creates fully customizable text based on your prompts, including but not limited to tables of content, action items, memos, and detailed analyses. <Note title="Notes"> - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. - This endpoint supports streaming responses. For details on integrating this feature into your application, refer to the [Open-ended analysis](/v1.3/docs/guides/analyze-videos/open-ended-analysis#streaming-responses). </Note>

Authentication

x-api-keystring

Your API key.

Note

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

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 analyze a video and generate text based on its content.

video_idstringRequired

The unique identifier of the video for which you wish to generate a text.

promptstringRequired

A prompt that guides the model on the desired format or content.

Notes

Even though the model behind this endpoint is trained to a high degree of accuracy, the preciseness of the generated text may vary based on the nature and quality of the video and the clarity of the prompt.
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.

Examples:

Based on this video, I want to generate five keywords for SEO (Search Engine Optimization).
I want to generate a description for my video with the following format: Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.

A prompt that guides the model on the desired format or content. <Note title="Notes"> - Even though the model behind this endpoint is trained to a high degree of accuracy, the preciseness of the generated text may vary based on the nature and quality of the video and the clarity of the prompt. - 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> **Examples**: - Based on this video, I want to generate five keywords for SEO (Search Engine Optimization). - I want to generate a description for my video with the following format: Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.

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

streambooleanOptionalDefaults to true

Set this parameter to true to enable streaming responses in the NDJSON format.

Default: true

Set this parameter to `true` to enable streaming responses in the <a href="https://github.com/ndjson/ndjson-spec" target="_blank">NDJSON</a> format. **Default:** `true`

response_formatobjectOptional

Use this parameter to specify the format of the response. When 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 processed.

Note

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

The specified video has successfully been processed. <Note title="Note"> The maximum length of the response is 4,096 tokens. </Note>

Streamed responseobject

Non-streamed responseobject

Errors

A prompt that guides the model on the desired format or content.

Notes

Even though the model behind this endpoint is trained to a high degree of accuracy, the preciseness of the generated text may vary based on the nature and quality of the video and the clarity of the prompt.
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.

Examples:

Based on this video, I want to generate five keywords for SEO (Search Engine Optimization).
I want to generate a description for my video with the following format: Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.

1	curl -X POST https://api.twelvelabs.io/v1.3/analyze \
2	-H "x-api-key: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"video_id": "6298d673f1090f1100476d4c",
6	"prompt": "I want to generate a description for my video with the following format - Title of the video, followed by a summary in 2-3 sentences, highlighting the main topic, key events, and concluding remarks.",
7	"temperature": 0.2,
8	"stream": true,
9	"response_format": {
10	"type": "json_schema",
11	"json_schema": {
12	"type": "object",
13	"properties": {
14	"title": {
15	"type": "string"
16	},
17	"summary": {
18	"type": "string"
19	},
20	"keywords": {
21	"type": "array",
22	"items": {
23	"type": "string"
24	}
25	}
26	}
27	}
28	},
29	"max_tokens": 2000
30	}'

1	{
2	"event_type": "stream_start"
3	}