API ReferenceAnalyze and segment videos

Create an async analysis task

This method asynchronously analyzes your videos. It supports two modes: general analysis (prompt-based text generation) with Pegasus 1.2 and video segmentation with Pegasus 1.5. <Accordion title="Input requirements"> - Minimum duration: 4 seconds - Maximum duration: 2 hours - 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**: - Generate custom text from your video using a prompt (Pegasus 1.2 only) - Extract timestamped metadata with custom fields from your video (Pegasus 1.5 only) - Analyze videos longer than 1 hour - Process videos asynchronously without blocking your application **Do not use this method for**: - Videos for which you need immediate results or real-time streaming. Use the [`POST`](/v1.3/api-reference/analyze-videos/sync-analysis) method of the `/analyze` endpoint instead. Analyzing videos asynchronously requires three steps: 1. Create an analysis task using this method. The platform returns a task ID. 2. Poll the status of the task using the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint. Wait until the status is `ready`. 3. Retrieve the results from the response when the status is `ready` using the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint. <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 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.
videoobjectRequired
An object specifying the source of the video content. Include exactly one source.
model_nameenumOptionalDefaults to pegasus1.2

The video understanding model to use for analysis.

  • pegasus1.2 (default): Analyzes pre-indexed videos. Pass a video_id to reference your video.
  • pegasus1.5: Analyzes videos directly from a URL, asset, or base64 string. Supports video segmentation with custom segment definitions.
Allowed values:
promptstringOptional

A natural-language text that provides instructions for analyzing the video. Required for general-mode analysis. Not supported when analysis_mode is time_based_metadata.

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

Sets the analysis mode to time_based_metadata, which segments your video into time-based intervals and extracts custom metadata for each segment. Requires model_name set to pegasus1.5 and response_format.type set to segment_definitions.

Allowed values:
temperaturedoubleOptional

Controls the randomness of the text output.

Default: 0.2 Min: 0 Max: 1

max_tokensintegerOptional1-32768

The maximum number of tokens to generate. The allowed range depends on the model:

  • pegasus1.2: Min: 1, Max: 4,096
  • pegasus1.5: Min: 2,048, Max: 32,768, Default: 32,768
response_formatobjectOptional

Controls the response format. When you omit this parameter, you receive unstructured text.

  • json_schema: Return structured JSON that conforms to your schema.
  • segment_definitions: Extract timestamped metadata with custom fields from your video. Requires model_name set to pegasus1.5 and analysis_mode set to time_based_metadata.
min_segment_durationdoubleOptional>=2

Minimum duration for each extracted segment, in seconds. Set this to prevent the model from creating very short segments. Requires model_name set to pegasus1.5 and analysis_mode set to time_based_metadata.

Min: 2

max_segment_durationdoubleOptional>=2

Maximum duration for each extracted segment, in seconds. Set this to break long continuous sections into shorter segments. Must be greater than or equal to min_segment_duration. Requires model_name set to pegasus1.5 and analysis_mode set to time_based_metadata.

Min: 2

Response

Analysis task created successfully.
task_idstring
The unique identifier of the analysis task.
statusenum
The current status of the analysis task.
Allowed values:

Errors

400
Bad Request Error
500
Internal Server Error