Sync analysis

Changed on

This method analyzes a video or one or more images and returns the results directly in the response. Each request must contain a video or one or more images, but not both. You can use general analysis (prompt-based text generation) with either media type.

<Accordion title="Input requirements"> **Videos** - Minimum duration: 1 second - 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.

Images

  • You can provide one to twenty images per request.
  • Formats: JPEG, PNG, WebP, GIF, and BMP.
  • Maximum size: 20 MB per image.
  • Maximum pixel count: 16,777,216 pixels per image (width × height). </Accordion>

When to use this method:

  • Analyze videos up to 1 hour, or analyze images
  • 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 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

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/analyze
  • Auth: API key in header x-api-key

Request body

model_name'pegasus1.6' | 'pegasus1.5'

The video understanding model to use for analysis.

  • pegasus1.6: For details about this version, see the Pegasus 1.6 page.
  • pegasus1.5: For details about this version, see the Pegasus 1.5 page.

Default: pegasus1.5

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

start_timenumber double

Start of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with end_time to analyze only a portion of the video.

<Note title="Notes"> - If omitted, defaults to the internal start time of the video. - 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 the video duration. The window (`end_time - start_time`) must be at least 1 second. </Note>
end_timenumber double

End of the analysis window, as an absolute timestamp in seconds, based on the internal metadata of the video. Use with start_time to analyze only a portion of the video.

<Note title="Notes"> - If omitted, defaults to the internal start time of the video 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 window (`end_time - start_time`) must be at least 1 second. </Note>

Response

The specified video has successfully been analyzed.

OR

Changes

  • 8b021f9a1426Revision changes
    • info

      added the new optional request property

    • info

      added the new pegasus1.6 enum value to the request property

  • 69c273061729Revision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property // to the response with the status