Sync analysis | TwelveLabs

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 polling for task completion
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.
Video segmentation with custom segment definitions. Use the POST method of the /analyze/tasks endpoint with the model_name parameter set to pegasus1.5 instead.

On the Free plan, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the Video hours and video count limits section.

Note

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

This method analyzes your videos and returns the results directly in the response. It generates text based on your prompts and supports both Pegasus 1.2 and Pegasus 1.5 for general analysis (prompt-based text generation). <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 polling for task completion - 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. - Video segmentation with custom segment definitions. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint with the `model_name` parameter set to `pegasus1.5` instead. On the Free plan, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the [Video hours and video count limits](/v1.3/docs/concepts/indexes#video-hours-and-video-count-limits) section. <Note title="Note"> 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

Defines the synchronous analysis request. The required parameters depend on the model_name parameter.

model_nameenumOptionalDefaults to pegasus1.2

The video understanding model to use for analysis.

pegasus1.2: General analysis (prompt-based text generation).
pegasus1.5: General analysis (prompt-based text generation) with video clipping, structured prompts with reference images, and video segmentation (async only). See the Pegasus page for token limits.

Default: pegasus1.2

The video understanding model to use for analysis. - `pegasus1.2`: General analysis (prompt-based text generation). - `pegasus1.5`: General analysis (prompt-based text generation) with video clipping, structured prompts with reference images, and video segmentation (async only). See the [Pegasus](/v1.3/docs/concepts/models/pegasus#context-window) page for token limits. **Default:** `pegasus1.2`

Allowed values:

video_idstringOptional

The unique identifier of the video to analyze. Use this parameter when the model_name parameter is pegasus1.2. Not supported with pegasus1.5.

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

The unique identifier of the video to analyze. Use this parameter when the `model_name` parameter is `pegasus1.2`. Not supported with `pegasus1.5`. <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.

promptstringOptional

A text prompt that guides the model on the desired format or content. Works with both Pegasus 1.2 and Pegasus 1.5. To include reference images in your prompt, use the prompt_v2 parameter instead (Pegasus 1.5 only). Mutually exclusive with the prompt_v2 parameter.

Your prompts can be instructive or descriptive, or you can phrase them as questions. Pegasus 1.2 limits prompts to 2,000 tokens. For Pegasus 1.5, this text counts toward the context window.

A text prompt that guides the model on the desired format or content. Works with both Pegasus 1.2 and Pegasus 1.5. To include reference images in your prompt, use the `prompt_v2` parameter instead (Pegasus 1.5 only). Mutually exclusive with the `prompt_v2` parameter. Your prompts can be instructive or descriptive, or you can phrase them as questions. Pegasus 1.2 limits prompts to 2,000 tokens. For Pegasus 1.5, this text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).

prompt_v2objectOptional

A structured prompt with <@name> placeholders for referencing images. Requires the model_name parameter set to pegasus1.5. Mutually exclusive with the prompt parameter.

The prompt text and reference images count toward the context window.

A structured prompt with `<@name>` placeholders for referencing images. Requires the `model_name` parameter set to `pegasus1.5`. Mutually exclusive with the `prompt` parameter. The prompt text and reference images count toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).

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. Only the json_schema type is supported for synchronous analysis.

max_tokensintegerOptional2-98304

The maximum response length, in tokens. The allowed range depends on the model:

Model	Min	Max	Default
Pegasus 1.2	2	4,096	4,096
Pegasus 1.5	512	98,304	4,096

The maximum response length, in tokens. The allowed range depends on the model: | Model | Min | Max | Default | |-------|-----|-----|---------| | Pegasus 1.2 | 2 | 4,096 | 4,096 | | Pegasus 1.5 | 512 | 98,304 | 4,096 |

start_timedoubleOptional

Start of the analysis window, as an absolute timestamp in seconds, based on the video’s internal metadata. Use with end_time to analyze only a portion of the video. Requires model_name set to pegasus1.5.

Notes

If omitted, defaults to the video’s internal start time.
Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4.
Must be less than end_time and less than the video duration. The clip (end_time - start_time) must be at least 4 seconds.

Start of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `end_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time. - Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. - Must be less than `end_time` and less than the video duration. The clip (`end_time - start_time`) must be at least `4` seconds. </Note>

end_timedoubleOptional

End of the analysis window, as an absolute timestamp in seconds, based on the video’s internal metadata. Use with start_time to analyze only a portion of the video. Requires model_name set to pegasus1.5.

Notes

If omitted, defaults to the video’s internal start time plus its duration.
Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4.
Must be greater than start_time and less than or equal to the video duration. The clip (end_time - start_time) must be at least 4 seconds.

End of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `start_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time plus its duration. - Most videos start at 0, but some (for example, from cameras or broadcast recordings) may have a non-zero start time. To find the value, run `ffprobe -v error -show_entries format=start_time,duration -of default=noprint_wrappers=1 your_video.mp4`. - Must be greater than `start_time` and less than or equal to the video duration. The clip (`end_time - start_time`) must be at least `4` seconds. </Note>

Response headers

X-Ratelimit-Limitdouble

The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.

X-Ratelimit-Remainingdouble

The number of requests remaining in the current rate limit window for the specific endpoint.

X-Ratelimit-Useddouble

The number of requests you have made in the current rate limit window for the specific endpoint.

X-Ratelimit-Resetdouble

The time at which the current rate limit window resets, expressed in UTC epoch seconds.

Transfer-Encodingstring

Response

The specified video has successfully been analyzed.

Streamed responseobject

When the value of the stream parameter is set to true, the platform provides a streaming response in the NDJSON format.

The stream contains three types of events:

Stream start
Text generation
Stream end

To integrate the response into your application, follow the guidelines below:

Parse each line of the response as a separate JSON object.
Check the event_type field to determine how to handle the event.
For text_generation events, process the text field as it arrives. Depending on your application’s requirements, this may involve displaying the text incrementally, storing it for later use, or performing any tasks.
Use the stream_start and stream_end events to manage the lifecycle of your streaming session.

Non-streamed responseobject

When the value of the stream parameter is set to false, the response is as follows:

Errors

400

Bad Request Error

404

Not Found Error

429

Too Many Requests Error

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 polling for task completion
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.
Video segmentation with custom segment definitions. Use the POST method of the /analyze/tasks endpoint with the model_name parameter set to pegasus1.5 instead.

On the Free plan, you have a total of 600 minutes (10 hours) shared across indexing, analysis, and segmentation. For details, see the Video hours and video count limits section.

Note

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

$	curl -X POST https://api.twelvelabs.io/v1.3/analyze \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"video_id": "6298d673f1090f1100476d4c",
>	"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.",
>	"temperature": 0.2,
>	"stream": true,
>	"response_format": {
>	"type": "json_schema",
>	"json_schema": {
>	"type": "object",
>	"properties": {
>	"title": {
>	"type": "string"
>	},
>	"summary": {
>	"type": "string"
>	},
>	"keywords": {
>	"type": "array",
>	"items": {
>	"type": "string"
>	}
>	}
>	}
>	}
>	},
>	"max_tokens": 2000
>	}'

1	{
2	"event_type": "stream_start",
3	"id": "2a22fd17-7bd4-446a-abd6-b9382cb18f90",
4	"data": "1. Vlog\\n2. Minnesota\\n3. Mall of America\\n4. Shopping haul\\n5. Outdoor adventure",
5	"finish_reason": "stop",
6	"usage": {
7	"output_tokens": 100,
8	"input_tokens": 45
9	}
10	}