Sync analysis | TwelveLabs

This method synchronously analyzes your videos and generates fully customizable text based on your prompts.

Input requirements

Minimum duration: 4 seconds
Maximum duration: 1 hour
Formats: FFmpeg supported formats
Resolution: 360x360 to 5184x2160 pixels
Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1.

When to use this method:

Analyze videos up to 1 hour
Retrieve immediate results without waiting for asynchronous processing
Stream text fragments in real-time for immediate processing and feedback

Do not use this method for:

Videos longer than 1 hour. Use the POST method of the /analyze/tasks endpoint instead.

Notes

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

This method synchronously analyzes your videos and generates fully customizable text based on your prompts. <Accordion title="Input requirements"> - Minimum duration: 4 seconds - Maximum duration: 1 hour - Formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html) - Resolution: 360x360 to 5184x2160 pixels - Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1. </Accordion> **When to use this method**: - Analyze videos up to 1 hour - Retrieve immediate results without waiting for asynchronous processing - Stream text fragments in real-time for immediate processing and feedback **Do not use this method for**: - Videos longer than 1 hour. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint instead. <Note title="Notes"> - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>

Authentication

x-api-keystring

Your API key.

Note

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

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

Request

This endpoint expects an object.

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.

video_idstringOptional

The unique identifier of the video to analyze.

This parameter will be deprecated and removed in a future version. Use the video parameter instead.

The unique identifier of the video to analyze. <Info> This parameter will be deprecated and removed in a future version. Use the [`video`](/v1.3/api-reference/analyze-videos/sync-analysis#request.body.video) parameter instead.</Info>

videoobjectOptional

An object specifying the source of the video content. Include exactly one source.

temperaturedoubleOptional

Controls the randomness of the 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

Specifies the format of the response. When you omit this parameter, the platform returns unstructured text.

max_tokensintegerOptional1-4096

The maximum number of tokens to generate.

Min: 1 Max: 4096

Response

The specified video has successfully been analyzed.

Note

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

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

Streamed responseobject

Non-streamed responseobject

Errors

400

Bad Request Error

429

Too Many Requests Error

This method synchronously analyzes your videos and generates fully customizable text based on your prompts.

Input requirements

Minimum duration: 4 seconds
Maximum duration: 1 hour
Formats: FFmpeg supported formats
Resolution: 360x360 to 5184x2160 pixels
Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1.

When to use this method:

Analyze videos up to 1 hour
Retrieve immediate results without waiting for asynchronous processing
Stream text fragments in real-time for immediate processing and feedback

Do not use this method for:

Videos longer than 1 hour. Use the POST method of the /analyze/tasks endpoint instead.

Notes

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

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	"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.",
6	"video_id": "6298d673f1090f1100476d4c",
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	}