Sign in

v3

latestOpenAPI 3.1.02026-07-3197486526.1 KB

Sync analysis

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 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 title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>
post/analyze

Headers

x-api-keystring required

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 body

model_name'pegasus1.2' | 'pegasus1.5'

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

video_idstring

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 parameter instead.</Info>

promptstring

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

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.

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.
temperaturenumber double

Controls the randomness of the text output.

Default: 0.2 Min: 0 Max: 1

streamboolean

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

max_tokensinteger

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

ModelMinMaxDefault
Pegasus 1.224,0964,096
Pegasus 1.551298,3044,096
start_timenumber double

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_timenumber double

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

The specified video has successfully been analyzed.

OR