For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
This method asynchronously analyzes your videos. It supports two analysis modes: general analysis (prompt-based text generation) and video segmentation with custom segment definitions. Video segmentation requires 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 (general analysis)
- Extract timestamped metadata with custom segment definitions 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>
This method asynchronously analyzes your videos. It supports two analysis modes: general analysis (prompt-based text generation) and video segmentation with custom segment definitions. Video segmentation requires Pegasus 1.5.
Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1.
When to use this method:
Generate custom text from your video using a prompt (general analysis)
Extract timestamped metadata with custom segment definitions 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 method of the /analyze endpoint instead.
Analyzing videos asynchronously requires three steps:
Create an analysis task using this method. The platform returns a task ID.
Poll the status of the task using the GET method of the /analyze/tasks/{task_id} endpoint. Wait until the status is ready.
Retrieve the results from the response when the status is ready using the GET method of the /analyze/tasks/{task_id} endpoint.
Note
This endpoint is rate-limited. For details, see the Rate limits page.
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: 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. See the Pegasus page for token limits.
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 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
Natural-language instructions for analyzing the video. Required for general analysis (prompt-based text generation). Not supported when analysis_mode is time_based_metadata. 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.
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.
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.
analysis_modeenumOptionalDefaults to general
The analysis approach for this task.
general: Analyze the video and generate a response based on your prompt. Supports both free-form text and structured output via response_format.
time_based_metadata: Segment the video into time-based intervals and extract custom metadata for each segment. Requires model_name set to pegasus1.5 and response_format.type set to segment_definitions.
Default:general
Allowed values:
temperaturedoubleOptional
Controls the randomness of the text output.
Default: 0.2 Min: 0 Max: 1
max_tokensintegerOptional1-98304
The maximum response length, in tokens. The allowed range depends on the model and analysis mode:
Model
Mode
Min
Max
Default
Pegasus 1.2
—
1
4,096
4096
Pegasus 1.5
general
512
98,304
4,096
Pegasus 1.5
time_based_metadata
2,048
98,304
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 value to enforce a minimum segment length. Requires model_name set to pegasus1.5 and analysis_mode set to time_based_metadata. Mutually exclusive with response_format.segment_definitions[].time_ranges.
Min: 2
max_segment_durationdoubleOptional>=2
Maximum duration for each extracted segment, in seconds. Set this value to split 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. Mutually exclusive with response_format.segment_definitions[].time_ranges.
Min: 2
start_timedoubleOptional
Start of the analysis window, in seconds. Use with end_time to analyze only a portion of the video. Requires model_name set to pegasus1.5.
Notes
If omitted, defaults to 0.
Must be less than end_time and less than the video duration. The clip (end_time - start_time) must be at least 4 seconds.
Mutually exclusive with response_format.segment_definitions[].time_ranges.
Together with end_time, this parameter determines the billable video duration. If you omit both, billing uses the full video duration. For details, see the Frequently asked questions page.
end_timedoubleOptional
End of the analysis window, in seconds. 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 duration.
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.
Mutually exclusive with response_format.segment_definitions[].time_ranges.
Together with start_time, this parameter determines the billable video duration. If you omit both, billing uses the full video duration. For details, see the Frequently asked questions page.
