---
title: "Create an async analysis task"
method: POST
path: "/analyze/tasks"
tags: ["analyzeAsync > tasks"]
---

# Create an async analysis task

`POST /analyze/tasks`

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.

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 title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Headers

- `x-api-key` string, required

## Request body

- CreateAsyncAnalyzeRequest — Defines the asynchronous analysis request.
  - `model_name` 'pegasus1.2' | 'pegasus1.5' — 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](/v1.3/docs/concepts/models/pegasus#context-window) page for token limits. **Default:** `pegasus1.2`
  - `custom_id` string — 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`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint - The [`GET`](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks) 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.
  - `video` union, required — An object specifying the source of the video content. Include exactly one source.
    - object — Provide the video via a URL.
      - `type` 'url', required — Discriminator value: url
      - `url` string, uri, required — The publicly accessible URL of the video file. Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported.
    - object — Provide the video via a unique identifier of an asset.
      - `type` 'asset_id', required — Discriminator value: asset_id
      - `asset_id` string, required — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - object — Provide the video via base64-encoded data.
      - `type` 'base64_string', required — Discriminator value: base64_string
      - `base64_string` string, required — The base64-encoded video data. The maximum size is 30MB.
  - `prompt` string — 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](/v1.3/docs/concepts/models/pegasus#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_v2` AnalyzePromptV2 — A structured prompt with `<@name>` placeholders for referencing images. Requires the `model_name` parameter set to `pegasus1.5`. Not supported when the `analysis_mode` parameter is `time_based_metadata`. Mutually exclusive with the `prompt` parameter.
    - `input_text` string, required — The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources` (Example: `"Is there a <@tiger-1> in the video?"`). For Pegasus 1.5, this text counts toward the [context window](/v1.3/docs/concepts/models/pegasus#context-window).
    - `media_sources` SMEMediaSource[] — Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources.
      - `name` string, required — A descriptive name for this media source.
      - `media_type` 'image', required — The media type. Only `image` is available.
      - `url` string, uri — A publicly accessible HTTPS URL of the image.
      - `asset_id` string — The unique identifier of an uploaded asset.
      - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
  - `analysis_mode` 'general' | 'time_based_metadata' — 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`
  - `temperature` number, double — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1
  - `max_tokens` integer — The maximum response length, in tokens. The allowed range depends on the model and analysis mode: | Model | Mode | Min | Max | Default | |-------|------|-----|-----|---------| | Pegasus 1.2 | — | 2 | 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_format` AsyncResponseFormat — 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`.
    - `type` 'json_schema' | 'segment_definitions', required — The response format to use. - `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`.
    - `json_schema` AsyncResponseFormatJsonSchema — 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. **Supported types** - `array` - `boolean` - `integer` - `null` - `number` - `object` - `string` - `timestamp` (Pegasus 1.5 only) **Supported constraints** | Type | Supported keywords | Notes | |------|-------------------|-------| | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).<br/>- `exclusiveMaximum`: Sets the highest allowed value (exclusive).<br/>- `minimum`: Sets the lowest allowed value (inclusive).<br/>- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).<br/>These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.<br/>- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.<br/>See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas. - `required`: Specifies mandatory properties.<br/>See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.<br/>See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.<br/>See the **Timestamp type** section below. | **String limitations** When you use the `string` type: - The platform validates strings using only `pattern` and `format`. Including `minLength` or `maxLength` causes a 422 error: "String length constraints (minLength) are not supported." Remove these keywords from your schema. **Object limitations** When you use the `object` type: - The platform does not support the `additionalProperties` keyword. Including it causes a 422 error. Remove it from your schema. - The platform returns properties in declaration order. - Make the first property required. If the first property is optional, the platform moves the first required property to the beginning. **Array limitations** When you use the `array` type: - The platform does not support `uniqueItems` or `maxItems`. Including either keyword causes a 422 error. Remove them from your schema. **Constant and enumerated values** The `const` and `enum` keywords support the following types: - `boolean` - `null` - `number` - `string` **Schema composition** The platform supports only `anyOf` for [schema composition](https://json-schema.org/understanding-json-schema/reference/combining). **Annotations** The platform accepts but ignores JSON schema annotations like `title`, `$comments`, and `description`. **Subschema references** You can reference subschemas using `$ref` with these requirements: - Define subschemas within `$defs`. - Use valid URIs that point to the internal subschema. For details, see the [JSON Schema documentation on $defs](https://json-schema.org/understanding-json-schema/structuring#defs). **Timestamp type (Pegasus 1.5 only)** Declare a property as `{"type": "timestamp", "format": "<format>"}` to control the format of the returned value. The `format` field accepts the following values: | `format` | Example output | Notes | |----------|----------------|-------| | `seconds` | `10.5` | Returns a JSON number in seconds. | | `hh:mm:ss` | `"00:01:23"` | Rounded to the nearest second. Negative values are converted to `"00:00:00"`. | | `hh:mm:ss.fff` | `"00:01:23.500"` | Millisecond precision. | The type of the response depends on the value of the `format` field: `seconds` returns a JSON number, while `hh:mm:ss` and `hh:mm:ss.fff` return a JSON string. *Supported positions* You can declare `timestamp` fields at the top level of your schema or inside objects nested one level within an array: - Top level: `properties.<field_name>` - Inside an array: `properties.<array_field>.items.properties.<field_name>` Declaring `timestamp` outside these positions — deeper nesting, inside `oneOf` / `anyOf` / `allOf`, or inside `$ref` — is not supported and is rejected with HTTP 400. *Validation errors* When `format` is missing or invalid, the platform returns `400 parameter_invalid`: ``` response_format.json_schema.properties.<name>.format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** For Pegasus 1.5, properties named `start_time` or `end_time` in your response schema receive special type handling at any nesting depth (including inside array `items`). These are unrelated to the top-level `start_time` / `end_time` request parameters or `time_ranges`. The platform returns the value in a format determined by the declared type: *Allowed declarations:* | Declared type | Platform behavior | |---------------|-------------------| | `number` | Passes the value through without conversion. | | `integer` | Rounds the value to the nearest integer. | | `string` (no `format`) | Converts the value to the `hh:mm:ss.fff` format. | | `timestamp` with `format` | See the **Timestamp type** section above for the available formats. | *Rejected declarations (returns `400` error):* - `string` with any `format` keyword (`time`, `date-time`, `email`, `uri`, etc.) - `boolean` - `object` - `array` - `null` All other property names in your schema remain unconstrained by these rules. For other field names, use the `timestamp` type described above. **Response validation** Check the `FinishReason` field to verify your JSON response is complete: - When `FinishReason` is `stop`, the generation completed normally, and the JSON is valid and complete. - When `FinishReason` is `length`, the platform truncates the response at the maximum response length or the context window. This may result in truncated, invalid JSON that fails to parse.
    - `segment_definitions` SegmentDefinition[] — Define the types of segments to extract from your video. 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.
      - `id` string, required — A unique identifier for this segment definition.
      - `description` string, required — Describe what this type of segment looks like in the video. The model uses this text to identify matching segments.
      - `fields` SegmentField[] — Custom fields to extract for each segment instance.
        - `name` string, required — The name of the field.
        - `type` 'string' | 'boolean' | 'number' | 'integer' | 'array' | 'timestamp', required — The data type of the field. When set to `timestamp`, the `format` property is required and controls the format of the returned value. Requires the `model_name` parameter set to `pegasus1.5`.
        - `description` string, required — Instructions that guide the model on what this field should contain and how to extract it from the video.
        - `format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — The output format for `timestamp` fields. Required when `type` is `timestamp`. Must be omitted for any other type. | `format` | Example output | |----------|----------------| | `seconds` | `10.5` (JSON number in seconds) | | `hh:mm:ss` | `"00:01:23"` (rounded to the nearest second; negative values are converted to `"00:00:00"`) | | `hh:mm:ss.fff` | `"00:01:23.500"` (millisecond precision) | *Validation errors* The platform returns `400 parameter_invalid` (with field path `response_format.segment_definitions.fields.format`) when: - `type` is `timestamp` and `format` is missing, empty, or not one of the supported values. - `type` is not `timestamp` and `format` is set.
        - `enum` string[] — Allowed values for this field. Maximum 100 values. Not supported when `type` is `timestamp`.
        - `items` SegmentFieldItems — Required when `type` is `array`. Specifies the type of array elements. Not supported when `type` is `timestamp`.
          - `type` 'string' | 'number' | 'boolean' | 'integer', required
      - `media_sources` SMEMediaSource[] — Reference images that help the model identify segments. Maximum 4 sources.
        - `name` string, required — A descriptive name for this media source.
        - `media_type` 'image', required — The media type. Only `image` is available.
        - `url` string, uri — A publicly accessible HTTPS URL of the image.
        - `asset_id` string — The unique identifier of an uploaded asset.
        - `base64_string` string — Base64-encoded image data. The maximum size is 30MB.
      - `time_ranges` AnalyzeTimeRange[] — Time windows that limit segment extraction to specific parts of the video. Only supported for Pegasus 1.5 with `analysis_mode` set to `time_based_metadata`. <Note title="Notes"> - Each range must satisfy `end_time > start_time` with a minimum duration of `2` seconds. Both values must fall within the video duration. - Ranges within a single definition must not overlap. Touching boundaries are allowed (Example: `[0, 5]` and `[5, 10]`). - Mutually exclusive with the top-level `start_time` / `end_time` fields. - Mutually exclusive with `min_segment_duration` and `max_segment_duration`. - These time ranges control which portions of the `start_time`–`end_time` window are analyzed; the billable duration is always the full `start_time`–`end_time` span. </Note>
        - `start_time` number, double, required — The start of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be less than `end_time` and within the video 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`.
        - `end_time` number, double, required — The end of the window, as an absolute timestamp in seconds, based on the video's internal metadata. Must be greater than `start_time` by at least `2` seconds and within the video 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`.
    - `segment_time_format` 'seconds' | 'hh:mm:ss' | 'hh:mm:ss.fff' — 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` and the `model_name` parameter set to `pegasus1.5`. Omitting this parameter is equivalent to setting it to `seconds` — both return JSON numbers in seconds. | `segment_time_format` | Auto boundary output | |-----------------------|----------------------| | `seconds` (default) | JSON number in seconds (Example: `12.5`) | | `hh:mm:ss` | JSON string (Example: `"00:00:13"`) — rounded to the nearest second | | `hh:mm:ss.fff` | JSON string (Example: `"00:00:12.500"`) — millisecond precision | This parameter applies only to the automatic segment boundaries (`start_time` and `end_time`). Custom `timestamp` fields always use their own format, regardless of the value of this field.
  - `min_segment_duration` number, double — 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_duration` number, double — 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_time` number, double — Start of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `end_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time. - 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 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](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page. </Note>
  - `end_time` number, double — End of the analysis window, as an absolute timestamp in seconds, based on the video's internal metadata. Use with `start_time` to analyze only a portion of the video. Requires `model_name` set to `pegasus1.5`. <Note title="Notes"> - If omitted, defaults to the video's internal start time 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 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](/v1.3/docs/resources/frequently-asked-questions#how-is-video-segmentation-priced) page. </Note>

## Response `202`

Analysis task created successfully.

- CreateAnalyzeTaskResponse — Response when creating a new analysis task.
  - `task_id` string, required — The unique identifier of the analysis task.
  - `status` 'queued' | 'pending' | 'processing' | 'ready' | 'failed', required — The current status of the analysis task.

## Other responses

- `400` — Validation failure or inaccessible video
- `500` — Internal server error

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/b6d766c2c340/schema)