> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/v1.3/sdk-reference/python/analyze-videos/async-analysis/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. The `AnalyzeAsyncClient.TasksClient` class provides methods to analyze videos asynchronously, generate text, and extract structured, timestamped segments. The platform supports two analysis modes: general analysis (prompt-based text generation) and video segmentation with custom segment definitions. Both modes use Pegasus 1.5. **When to use this class**: * Generate custom text from your video 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 asynchronously without blocking your application **Do not use this class for**: * Videos for which you need immediate results or real-time streaming. Use the [`analyze`](/v1.3/sdk-reference/python/analyze-videos/sync-analysis#sync-analysis) method instead. #### Input requirements * 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](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 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](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page for examples. Analyzing videos asynchronously requires three steps: 1. Create an analysis task using the [`create`](#create-an-async-analysis-task) method. The platform returns a task identifier. 2. Poll the status of the task using the [`retrieve`](#retrieve-task-status-and-results) method. Wait until the status is `ready`. 3. Retrieve the results from the response when the status is `ready` using the [`retrieve`](#retrieve-task-status-and-results) 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**: **`Function signature`** ```python Function signature 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: ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs response = client.analyze_async.tasks.list( page=1, page_limit=10, ) print(f"Total tasks: {response.page_info.total_results}") for task in response.data: print(f" Task ID: {task.task_id}") print(f" Status: {task.status}") print(f" Created: {task.created_at}") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `page` | `int` | No | A number that identifies the page to retrieve. Default: `1`. | | `page_limit` | `int` | No | The number of items to return on each page. Default: `10`. Max: `50`. | | `status` | `AnalyzeTaskStatus` | No | Filter analysis tasks by status. Values: `queued`, `pending`, `processing`, `ready`, `failed`. | | `video_url` | `str` | No | Filter tasks by exact video source URL. | | `asset_id` | `str` | No | Filter tasks by asset ID. | | `analysis_mode` | `TasksListRequestAnalysisMode` | No | Filter tasks by the analysis mode used when creating the task. Values: `"general"`, `"time_based_metadata"`. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | **Return value**: Returns a `TasksListResponse` object. The `TasksListResponse` class contains the following properties: | Name | Type | Description | | ----------- | --------------------------- | --------------------------------------------------------- | | `data` | `List[AnalyzeTaskResponse]` | An array that contains up to `page_limit` analysis tasks. | | `page_info` | `PageInfo` | An object that provides information about pagination. | The `PageInfo` class contains the following properties: | Name | Type | Description | | ---------------- | --------------- | --------------------------------------------------- | | `limit_per_page` | `Optional[int]` | The number of items returned per page. | | `page` | `Optional[int]` | The current page number. | | `total_page` | `Optional[int]` | The total number of pages. | | `total_results` | `Optional[int]` | The total number of analysis tasks in your account. | For details about `AnalyzeTaskResponse`, see [Retrieve task status and results](#retrieve-task-status-and-results). **API Reference**: [List async analysis tasks](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks) ## Create an async analysis task **Description**: This method asynchronously analyzes your videos. It supports two analysis modes: general analysis (prompt-based text generation) and video segmentation with custom segment definitions. Both modes use Pegasus 1.5. 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](/v1.3/docs/concepts/indexes#video-hours-and-video-count-limits) section. > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def create( self, *, video: VideoContext, model_name: typing.Optional[CreateAsyncAnalyzeRequestModelName] = OMIT, custom_id: typing.Optional[str] = OMIT, prompt: typing.Optional[AnalyzeTextPrompt] = OMIT, prompt_v_2: typing.Optional[AnalyzePromptV2] = OMIT, analysis_mode: typing.Optional[CreateAsyncAnalyzeRequestAnalysisMode] = OMIT, temperature: typing.Optional[AnalyzeTemperature] = OMIT, max_tokens: typing.Optional[int] = 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: ``` **`General analysis example`** ```python General analysis example from twelvelabs import TwelveLabs from twelvelabs.types import VideoContext_Url, AnalyzePromptV2 task = client.analyze_async.tasks.create( video=VideoContext_Url( url="", ), prompt_v_2=AnalyzePromptV2( input_text="", ), temperature=0.2, ) print(f"Task ID: {task.task_id}") print(f"Status: {task.status}") ``` **`Segmentation example`** ```python Segmentation example from twelvelabs import TwelveLabs from twelvelabs.types import ( VideoContext_Url, AsyncResponseFormat, SegmentDefinition, SegmentField, SegmentFieldItems, ) task = client.analyze_async.tasks.create( model_name="pegasus1.5", video=VideoContext_Url( url="", ), analysis_mode="time_based_metadata", response_format=AsyncResponseFormat( type="segment_definitions", segment_definitions=[ SegmentDefinition( id="scene", description="A distinct scene or setting change in the video", fields=[ SegmentField( name="sentiment", type="string", description="The emotional tone of this segment", enum=["positive", "negative", "neutral"], ), SegmentField( name="key_objects", type="array", description="Notable objects visible in this segment", items=SegmentFieldItems(type="string"), ), ], ), ], ), min_segment_duration=5.0, max_segment_duration=30.0, ) print(f"Task ID: {task.task_id}") print(f"Status: {task.status}") ``` **Parameters**: | Name | Type | Required | Description | | ---------------------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_name` | `CreateAsyncAnalyzeRequestModelName` | No | The video understanding model to use for analysis. Values: - `"pegasus1.5"`: General analysis (prompt-based text generation) with video clipping, structured prompts with reference images, and video segmentation. See the [Pegasus](/v1.3/docs/concepts/models/pegasus#context-window) page for token limits. **Default:** `"pegasus1.5"` | | `custom_id` | `str` | No | 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. Must match the pattern `^[a-zA-Z0-9_-]{1,64}$`. | | `video` | `VideoContext` | Yes | An object that specifies the source of the video. See [VideoContext](#videocontext) for details. | | `prompt` | `str` | No | 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_v_2` parameter instead. Mutually exclusive with the `prompt_v_2` parameter. | | `prompt_v_2` | `AnalyzePromptV2` | No | A structured prompt with the `<@name>` placeholders for referencing images. Not supported when the `analysis_mode` parameter is `"time_based_metadata"`. Mutually exclusive with the `prompt` parameter. See [AnalyzePromptV2](#analyzepromptv2). | | `analysis_mode` | `CreateAsyncAnalyzeRequestAnalysisMode` | No | The analysis approach for this task. Values: - `"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"` | | `temperature` | `float` | No | Controls the randomness of the text output. **Default:** 0.2, **Min:** 0, **Max:** 1 | | `max_tokens` | `int` | No | The maximum response length, in tokens. For `"pegasus1.5"` general mode: Min: `512`, Max: `98,304`, Default: `4,096`. For `"pegasus1.5"` `time_based_metadata` mode: Min: `2,048`, Max: `98,304`, Default: `32,768`. The input and response must fit within the [context window](/v1.3/docs/concepts/models/pegasus#context-window). With video segmentation, if the response needs more tokens than `max_tokens` allows, the task fails and no partial output is returned. | | `response_format` | `AsyncResponseFormat` | No | Controls the response format. When you omit this parameter, you receive unstructured text. | | `min_segment_duration` | `float` | No | Minimum duration for each extracted segment, in seconds. Prevents the model from creating very short segments. Requires `analysis_mode` set to `"time_based_metadata"`. Min: `2`. | | `max_segment_duration` | `float` | No | Maximum duration for each extracted segment, in seconds. Breaks long continuous sections into shorter segments. Must be greater than or equal to the `min_segment_duration` parameter. Requires `analysis_mode` set to `"time_based_metadata"`. Min: `2`. | | `start_time` | `float` | No | 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. 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](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page. | | `end_time` | `float` | No | 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. 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](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### VideoContext The `VideoContext` type specifies the source of the video. Provide exactly one of the following: | Class | Field | Type | Description | | --------------------------- | ---------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `VideoContext_Url` | `url` | `str` | The publicly accessible URL of the video file or HLS manifest. Use direct links to raw media files, or the URL of a VOD HLS manifest. Live video streams are rejected with a `400` error. Video hosting platforms and cloud storage sharing links are not supported. For HLS sources, if the duration cannot be determined, the platform calculates it from the manifest and the duration limits apply to that value. | | `VideoContext_AssetId` | `asset_id` | `str` | The unique identifier of an asset from a [direct](/v1.3/sdk-reference/python/upload-content/direct-uploads) or [multipart](/v1.3/sdk-reference/python/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) to check the status. | | `VideoContext_Base64String` | `base_64_string` | `str` | The base64-encoded video data. The maximum size is 30 MB. | The `AsyncResponseFormat` class contains the following properties: | Name | Type | Description | | --------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `AsyncResponseFormatType` | The response format to use. Values: `"json_schema"` (structured JSON conforming to a provided schema), `"segment_definitions"` (timestamped metadata with custom fields, requires `analysis_mode` set to `"time_based_metadata"`). | | `json_schema` | `Optional[Dict[str, Optional[Any]]]` | Contains the JSON schema that defines the response structure. The schema must adhere to the [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) specification. For details, see the [`json_schema`](/v1.3/api-reference/analyze-videos/sync-analysis#request.body.response_format.json_schema) parameter in the API Reference section. | | `segment_definitions` | `Optional[List[SegmentDefinition]]` | Define the types of segments to extract from your video. Required when `type` is `"segment_definitions"`. Minimum 1, maximum 20 definitions. The number of segment definitions affects billing. For details, see the [Frequently asked questions](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page. See [SegmentDefinition](/v1.3/sdk-reference/python/analyze-videos/async-analysis#segmentdefinition) for class details. | | `segment_time_format` | `Optional[AsyncResponseFormatSegmentTimeFormat]` | Set the output format for the automatic `start_time` and `end_time` keys returned on each segment. Requires the `type` parameter set to `"segment_definitions"`. Omitting this parameter is equivalent to setting it to `"seconds"`. Values: `"seconds"` (JSON number in seconds, Example: `12.5`), `"hh:mm:ss"` (JSON string rounded to the nearest second, Example: `"00:00:13"`), `"hh:mm:ss.fff"` (JSON string with millisecond precision, Example: `"00:00:12.500"`). This parameter applies only to the automatic segment boundaries. Custom `timestamp` fields always use their own declared format. | ### AnalyzePromptV2 The `AnalyzePromptV2` class defines a structured prompt with image references. | Name | Type | Required | Description | | --------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input_text` | `str` | Yes | The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window). | | `media_sources` | `Optional[List[SmeMediaSource]]` | No | Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources. See [SmeMediaSource](#smemediasource). | ### SegmentDefinition The `SegmentDefinition` class defines a type of segment to extract from the video. | Name | Type | Required | Description | | --------------- | -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `id` | `str` | Yes | A unique identifier for this segment definition. | | `description` | `str` | Yes | Describe what this type of segment looks like in the video. The model uses this text to identify matching segments. | | `fields` | `Optional[List[SegmentField]]` | No | Custom fields to extract for each segment instance. Maximum 20 fields. See [SegmentField](#segmentfield) for details. | | `media_sources` | `Optional[List[SmeMediaSource]]` | No | Reference images that help the model identify segments. Maximum 4 sources. See [SmeMediaSource](#smemediasource) for details. | ### SegmentField The `SegmentField` class defines a custom field to extract for each segment. | Name | Type | Required | Description | | ------------- | ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `str` | Yes | The name of the field. | | `type` | `SegmentFieldType` | Yes | The data type of the field. Values: `"string"`, `"boolean"`, `"number"`, `"integer"`, `"array"`, `"timestamp"`. When set to `"timestamp"`, the `format` property is required and controls the format of the returned value. | | `description` | `str` | Yes | Instructions that guide the model on what this field should contain and how to extract it from the video. | | `format` | `Optional[SegmentFieldFormat]` | No | The output format for `timestamp` fields. Required when `type` is `"timestamp"`. Must be omitted for any other type. Values: `"seconds"` (JSON number in seconds, Example: `10.5`), `"hh:mm:ss"` (JSON string rounded to the nearest second, Example: `"00:01:23"`), `"hh:mm:ss.fff"` (JSON string with millisecond precision, Example: `"00:01:23.500"`). | | `enum` | `Optional[List[str]]` | No | Allowed values for this field. Maximum 100 values. Not supported when `type` is `"timestamp"`. | | `items` | `Optional[SegmentFieldItems]` | No | Required when `type` is `"array"`. Specifies the type of array elements. The `items` object has a single property `type` with values: `"string"`, `"number"`, `"boolean"`, `"integer"`. Not supported when `type` is `"timestamp"`. | ### 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. | Name | Type | Required | Description | | ---------------- | ------------------------- | -------- | ---------------------------------------------------- | | `name` | `str` | Yes | A descriptive name for this media source. | | `media_type` | `SmeMediaSourceMediaType` | Yes | The media type. Value: `"image"`. | | `url` | `Optional[str]` | No | A publicly accessible HTTPS URL of the image. | | `asset_id` | `Optional[str]` | No | The unique identifier of an uploaded asset. | | `base_64_string` | `Optional[str]` | No | Base64-encoded image data. The maximum size is 30MB. | **Return value**: Returns a `CreateAnalyzeTaskResponse` object containing the task details. The `CreateAnalyzeTaskResponse` class contains the following properties: | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------ | | `task_id` | `str` | The unique identifier of the analysis task. | | `status` | `AnalyzeTaskStatus` | The initial status of the task. Value: `queued`. | **API Reference**: [Create an async analysis task](/v1.3/api-reference/analyze-videos/create-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 results are available. The `error` field describes the failure. Poll this method until `status` is `ready` or `failed`. When `status` is `ready`, use the results from the response. **Function signature and example**: **`Function signature`** ```python Function signature def retrieve( self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> AnalyzeTaskResponse: ``` **`Poll for task completion`** ```python Poll for task completion from twelvelabs import TwelveLabs import time while True: task = client.analyze_async.tasks.retrieve( task_id="", ) print(f"Status: {task.status}") if task.status == "ready": print(f"Generated text: {task.result.data}") print(f"Output tokens: {task.result.usage.output_tokens}") break elif task.status == "failed": print(f"Task failed: {task.error.message}") break else: time.sleep(5) ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ------------------------------------------- | | `task_id` | `str` | Yes | The unique identifier of the analysis task. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | **Return value**: Returns an `AnalyzeTaskResponse` object containing the task status and results. The `AnalyzeTaskResponse` class contains the following properties: | Name | Type | Description | | ---------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `task_id` | `str` | The unique identifier of the analysis task. | | `video_source` | `Optional[AnalyzeTaskResponseVideoSource]` | The video source you provided. | | `request_params` | `Optional[AnalyzeTaskResponseRequestParams]` | The parameters you sent when creating this task. | | `status` | `AnalyzeTaskStatus` | The current status of the task. Values: `queued`, `pending`, `processing`, `ready`, `failed`. | | `created_at` | `datetime` | The date and time when the task was created, in RFC 3339 format. | | `completed_at` | `Optional[datetime]` | The date and time when the task completed or failed, in RFC 3339 format. The platform returns this field only when `status` is `ready` or `failed`. | | `result` | `Optional[AnalyzeTaskResult]` | An object that contains the generated text and additional information. The platform returns this object only when `status` is `ready`. When the task fails, the response contains no `result` object, so `generation_id` and `usage` are absent. | | `error` | `Optional[AnalyzeTaskError]` | A message attached to the task response. The platform sets this field in the following cases: - `status` is `"failed"`: The `message` field describes the failure reason. With video segmentation, a task can fail because the analysis reached the maximum response length or the [context window](/v1.3/docs/concepts/models/pegasus#context-window) before it could complete. The response contains no `result` object. - `status` is `"ready"` and `result.finish_reason` is `"length"` (general analysis): The `message` field describes the truncation cause (either the maximum response length was reached or the context window was reached). The partial output is in `result.data`. Not set when `status` is `"ready"` and `result.finish_reason` is `"stop"`. | | `webhooks` | `Optional[List[AnalyzeTaskWebhookInfo]]` | The delivery status of each webhook endpoint. The platform omits this field when there are no webhooks configured. | The `AnalyzeTaskResponseVideoSource` class contains the following properties: | Name | Type | Description | | ----------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `type` | `Optional[AnalyzeTaskResponseVideoSourceType]` | The type of video source. Values: `"url"`, `"base64_string"`, `"asset_id"`. | | `url` | `Optional[str]` | The video URL. Present when `type` is `"url"`. | | `asset_id` | `Optional[str]` | The asset ID. Present when `type` is `"asset_id"`. | | `system_metadata` | `Optional[AnalyzeTaskResponseVideoSourceSystemMetadata]` | System-extracted video metadata. Present on a best-effort basis once the video has been processed. | The `AnalyzeTaskResponseVideoSourceSystemMetadata` class contains the following properties: | Name | Type | Description | | ---------- | ----------------- | ------------------------------ | | `duration` | `Optional[float]` | The video duration in seconds. | The `AnalyzeTaskResponseRequestParams` class contains the following properties: | Name | Type | Description | | ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `analysis_mode` | `Optional[AnalyzeTaskResponseRequestParamsAnalysisMode]` | The analysis approach for this task. Values: `"general"`, `"time_based_metadata"`. | | `prompt` | `Optional[str]` | The natural-language prompt for this task. Present only when `analysis_mode` is `general` and the task was created with `prompt` (not `prompt_v_2`). On the [List](#list-analysis-tasks) method, truncated to the first 30 characters; on the [Retrieve](#retrieve-task-status-and-results) method, returns the full text. | | `prompt_v_2` | `Optional[AnalyzeTaskResponseRequestParamsPromptV2]` | The structured prompt for this task. Present only when `analysis_mode` is `general` and the task was created with `prompt_v_2`. When present, the response excludes the flat `prompt` field. On the [List](#list-analysis-tasks) method, `input_text` is truncated to the first 30 characters; on the [Retrieve](#retrieve-task-status-and-results) method, returns the full text. | | `response_format` | `Optional[AnalyzeTaskResponseRequestParamsResponseFormat]` | The response format for this task. Present only when the request included a response format. | | `temperature` | `Optional[float]` | The temperature value for this analysis. | | `max_tokens` | `Optional[int]` | The maximum response length you set, in tokens. | | `min_segment_duration` | `Optional[float]` | The minimum segment duration you set, in seconds. Present when `analysis_mode` is `"time_based_metadata"`. | | `max_segment_duration` | `Optional[float]` | The maximum segment duration you set, in seconds. Present when `analysis_mode` is `"time_based_metadata"`. | | `start_time` | `Optional[float]` | The start of the analysis window, in seconds. Present only when the task was created with `start_time`. | | `end_time` | `Optional[float]` | The end of the analysis window, in seconds. Present only when the task was created with `end_time`. | The `AnalyzeTaskResult` class contains the following properties: | Name | Type | Description | | --------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `generation_id` | `str` | The unique identifier for the generation session. | | `data` | `str` | The generated text for this analysis task. When `analysis_mode` is not set, a plain-text string based on the prompt you provided. When `analysis_mode` is `"time_based_metadata"`, a JSON-encoded string keyed by segment definition `id`. Each key maps to an array of segment objects with `start_time` (number), `end_time` (number), and `metadata` (object with your custom fields). | | `finish_reason` | `FinishReason` | The reason the generation stopped. Values: `null` (generation has not finished), `"stop"` (the generation reached the end of the output text), `"length"` (the generation reached the maximum response length or the [context window](/v1.3/docs/concepts/models/pegasus#context-window); with a JSON response format, the output may be truncated and fail to parse). When the task uses general analysis, the partial output is in `data`, and a warning is in the task's `error` field. With video segmentation, if the analysis reaches either limit, the task fails and `"length"` never occurs. | | `usage` | `AnalyzeTaskResultUsage` | The number of tokens used in the generation. | The `AnalyzeTaskResultUsage` class contains the following properties: | Name | Type | Description | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `output_tokens` | `int` | The number of tokens in the generated text. | | `input_tokens` | `Optional[int]` | The number of tokens the input consumed. Together with `output_tokens`, this value must fit within the [context window](/v1.3/docs/concepts/models/pegasus#context-window). | The `AnalyzeTaskError` class contains the following properties: | Name | Type | Description | | --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `str` | A human-readable message. The platform sets this field in the following cases: **task failure** (`status` is `"failed"`) — describes the failure reason; **truncation warning** (general analysis, `finish_reason` is `"length"`) — to obtain the full output, increase `max_tokens` or reduce the input size, and the partial output is in `result.data`. With general analysis, check `finish_reason` instead of parsing the message text; with video segmentation, check `status`. For the message strings, see [Error codes](/v1.3/api-reference/error-codes#the-analyze-endpoint). | **API Reference**: [Retrieve analysis task status and results](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) ## 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**: **`Function signature`** ```python Function signature def delete( self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> None: ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.analyze_async.tasks.delete( task_id="", ) ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | ---------------- | -------- | ------------------------------------------- | | `task_id` | `str` | Yes | The unique identifier of the analysis task. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | **Return value**: Returns `None`. If successful, the platform returns a `204 No Content` response. **API Reference**: [Delete an analysis task](/v1.3/api-reference/analyze-videos/delete-analysis-task)