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:
custom_idstringOptionalformat: "^[a-zA-Z0-9_-]{1,64}$"

An optional identifier that you set when you create the task. Use this field to correlate tasks across responses, for example, to distinguish tasks by type or environment.

The platform stores this value unchanged and returns it in the following responses:

  • The GET method of the /analyze/tasks/{task_id} endpoint
  • The GET method of the /analyze/tasks endpoint
  • The analyze.task.ready and analyze.task.failed webhook payloads

Format: 1–64 characters. Alphanumeric, hyphens (-), and underscores (_) only. An empty string is rejected with a 400 Bad Request.

This field does not enforce uniqueness. You can submit multiple tasks with the same custom_id. To prevent duplicate task creation, use an Idempotency-Key header instead.

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