The AnalyzeAsyncClient.TasksClient class provides methods to analyze videos or images asynchronously, generate text, and extract structured, timestamped segments. Each request must contain a video or one or more images, but not both.

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

When to use this class:

• 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 class for:

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

In legacy billing, on the Free plan, analysis hours count toward a shared limit that also covers indexing - the number of segment definitions does not affect this limit. On paid plans, you pay based on how much video you process and how many segment definitions you include - see the Frequently asked questions page for examples. In the new billing, the allowances of your plan apply. See Plans, allowances, and overage.

Analyzing content asynchronously requires three steps:

1. Create an analysis task using the create method. The platform returns a task identifier.
2. Poll the status of the task using the retrieve method. Wait until the status is ready, failed, or canceled.
3. When the status is ready, retrieve the results using the retrieve method.

Methods

List analysis tasks

Description: This method returns a list of the analysis tasks in your account. The platform returns your analysis tasks sorted by creation date, with the newest at the top of the list.

Function signature and example:

def list(
    self,
    *,
    page: typing.Optional[int] = None,
    page_limit: typing.Optional[int] = None,
    status: typing.Optional[AnalyzeTaskStatus] = None,
    video_url: typing.Optional[str] = None,
    asset_id: typing.Optional[str] = None,
    analysis_mode: typing.Optional[TasksListRequestAnalysisMode] = None,
    request_options: typing.Optional[RequestOptions] = None,
) -> TasksListResponse:

Parameters:

Return value: Returns a TasksListResponse object.

The TasksListResponse class contains the following properties:

The PageInfo class contains the following properties:

For details about AnalyzeTaskResponse, see Retrieve task status and results.

API Reference: List async analysis tasks

Create an async analysis task

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

On the Free plan in legacy billing, 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. In the new billing, the allowances of your plan apply in place of this limit. See Plans, allowances, and overage.

Function signature and example:

def create(
    self,
    *,
    model_name: typing.Optional[CreateAsyncAnalyzeRequestModelName] = OMIT,
    custom_id: typing.Optional[str] = OMIT,
    video: typing.Optional[VideoContext] = OMIT,
    image: typing.Optional[typing.Sequence[AnalyzeImageInput]] = OMIT,
    prompt: typing.Optional[str] = OMIT,
    prompt_v_2: typing.Optional[AnalyzePromptV2] = OMIT,
    analysis_mode: typing.Optional[CreateAsyncAnalyzeRequestAnalysisMode] = OMIT,
    temperature: typing.Optional[AnalyzeTemperature] = OMIT,
    max_tokens: typing.Optional[CreateAsyncAnalyzeRequestMaxTokens] = OMIT,
    response_format: typing.Optional[AsyncResponseFormat] = OMIT,
    min_segment_duration: typing.Optional[float] = OMIT,
    max_segment_duration: typing.Optional[float] = OMIT,
    start_time: typing.Optional[float] = OMIT,
    end_time: typing.Optional[float] = OMIT,
    request_options: typing.Optional[RequestOptions] = None,
) -> CreateAnalyzeTaskResponse:

Parameters:

VideoContext

The VideoContext type specifies the source of the video. Provide exactly one of the following. Mutually exclusive with the image parameter.

AnalyzeImageInput

The AnalyzeImageInput class defines an image to analyze. Provide exactly one of the url, asset_id, or base64_string fields.

The AsyncResponseFormat class contains the following properties:

AnalyzePromptV2

The AnalyzePromptV2 class defines a structured prompt that uses <@name> placeholders to reference images. Mutually exclusive with the prompt and image parameters.

SegmentDefinition

The SegmentDefinition class defines a type of segment to extract from the video.

SegmentField

The SegmentField class defines a custom field to extract for each segment.

SegmentFieldItems

The SegmentFieldItems class defines the per-item structure of a segment field whose type is array or time_array. For an array field, the type value specifies the scalar element type. For a time_array field, use object as the type value and declare the fields of each event in the fields array.

TimeArrayItemField

The TimeArrayItemField class defines a field inside a time_array item. The platform adds start_time and end_time keys to every event automatically. You cannot declare fields with these names. A time_array field cannot contain another time_array field. The format property is not accepted on per-event fields.

SmeMediaSource

The SmeMediaSource class defines a reference image that provides visual context for segment identification. Provide exactly one of the url, asset_id, or base_64_string fields.

Return value: Returns a CreateAnalyzeTaskResponse object containing the task details.

The CreateAnalyzeTaskResponse class contains the following properties:

API Reference: Create an async analysis task

Retrieve task status and results

Description: This method retrieves the status and results of an analysis task.

Task statuses:

• queued: The task is waiting to be processed.
• pending: The task is queued and waiting to start.
• processing: The platform is analyzing the video.
• ready: Processing is complete. Results are available in the response.
• failed: The task failed. No result is available. The error field describes the failure.
• canceled: The task was canceled. No result is available. The error field describes the cancellation reason, if available.

The ready, failed, and canceled statuses are final.

Poll this method until status is ready, failed, or canceled. When status is ready, use the results from the response.

Function signature and example:

def retrieve(
    self,
    task_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> AnalyzeTaskResponse:

Parameters:

Return value: Returns an AnalyzeTaskResponse object containing the task status and results.

The AnalyzeTaskResponse class contains the following properties:

The AnalyzeTaskResponseVideoSource class contains the following properties:

The AnalyzeTaskResponseVideoSourceSystemMetadata class contains the following properties:

The AnalyzeTaskResponseRequestParams class contains the following properties:

The AnalyzeTaskMediaSource class contains the following properties:

The AnalyzeTaskResponseRequestParamsResponseFormat class contains the following properties:

The AnalyzeTaskResult class contains the following properties:

The AnalyzeTaskResultUsage class contains the following properties:

The AnalyzeTaskError class contains the following properties:

API Reference: Retrieve analysis task status and results

Cancel an async analysis task

Description: Use this method to cancel an asynchronous analysis task in your account. To cancel a task created as part of a batch, use the analyze_async.batches.cancel method.

You can cancel a task with the queued, pending, or processing status. This action cannot be undone.

Processing that has already started can continue briefly after cancellation.

When you cancel a task, the platform can send an analyze.task.canceled webhook. Delivery is best-effort: a 200 response is not a delivery guarantee. When you receive the event, retrieve the task for its current state.

Function signature and example:

def cancel(
    self,
    task_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> CancelAnalyzeTaskResponse

Parameters:

Return value: Returns a CancelAnalyzeTaskResponse containing task_id and the final status canceled. This response is also returned when the task was canceled by a previous request.

API Reference: Cancel an async analysis task

Delete an analysis task

Description: This method deletes an analysis task. You can only delete tasks that are not currently being processed.

Function signature and example:

def delete(
    self,
    task_id: str,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> None:

Parameters:

Return value: Returns None. If successful, the platform returns a 204 No Content response.

API Reference: Delete an analysis task