Skip to navigation
Models and searchAnalyze and segment videos

Create an async analysis task

This method analyzes a video or one or more images asynchronously. Each request must contain a video or one or more images, but not both.

The method supports two analysis modes:

  • General analysis: Prompt-based text generation with a video or one or more images.
  • Video segmentation: Timestamped metadata with custom segment definitions.

Videos

  • The video can be up to 2 hours long, or up to 4 hours when you analyze only a portion of it. You can analyze between 1 second and 2 hours of the video. HLS and base64 videos are limited to 2 hours.
  • Formats: FFmpeg supported formats
  • 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).

When to use this method:

  • Generate custom text from your video or one or more images using a prompt (general analysis)
  • Extract timestamped metadata with custom segment definitions from your video
  • Analyze videos longer than 1 hour, or a portion of a video up to 4 hours long
  • Process videos or images asynchronously without blocking your application

Do not use this method for:

  • Videos or images for which you need immediate results or real-time streaming. Use the POST method of the /analyze endpoint instead.

Analyzing content asynchronously requires three steps:

  1. Create an analysis task using this method. The platform returns a task identifier.
  2. Poll the status of the task using the GET method of the /analyze/tasks/{task_id} endpoint. Wait until the status is ready, failed, or canceled.
  3. When the status is ready, retrieve the results using the GET method of the /analyze/tasks/{task_id} endpoint.

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

This endpoint is rate-limited. For details, see the Rate limits page.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Request

This endpoint expects an object.
model_nameenumOptionalDefaults to 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

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, analyze.task.failed, and analyze.task.canceled 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.

videoobjectOptional

An object specifying the source of the video content. Include exactly one source. Mutually exclusive with the image parameter.

imagelist of objectsOptional

A list of up to twenty objects containing the images to analyze. For each image, include exactly one source. Requires Pegasus 1.6. Using any other model returns a parameter_invalid error.

Mutually exclusive with the video and prompt_v2 parameters. The prompt parameter is required when you provide images.

promptstringOptional

Natural-language instructions for analyzing the video or one or more images. 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. Mutually exclusive with the prompt_v2 parameter.

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

A structured prompt that uses <@name> placeholders to reference images. Mutually exclusive with the prompt and image parameters.

The prompt text and reference images count toward the context window.

analysis_modeenumOptionalDefaults to general

The analysis mode 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 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_tokensinteger or enumOptional

The maximum response length, in tokens. Provide an integer or the unlimited value.

The allowed integer range and default depend on the analysis mode:

ModeMinMaxDefault
general51298,3044,096
time_based_metadata2,04898,30432,768

  • Integer: With video segmentation, the task fails if the output exceeds the limit. No partial output is returned.

  • Unlimited: Removes the token limit from video segmentation. It requires analysis_mode set to time_based_metadata and model_name set to pegasus1.6. Mutually exclusive with response_format.segment_definitions[].time_ranges.

    The platform extracts as many segments as it can. If it stops before extracting every segment, the task still completes with the status field set to ready. The error field contains the warning that the results may be incomplete.

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

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 and at most 2 hours. The video may be up to 4 hours as long as the window stays within that limit.
  • 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, 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.

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 and at most 2 hours. The video may be up to 4 hours as long as the window stays within that limit.
  • 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.

Response

Analysis task created successfully.
task_idstring
The unique identifier of the analysis task.
statusenum

The current status of the analysis task. The ready, failed, and canceled statuses are final.

Errors

400
Bad Request Error
500
Internal Server Error