analyzeAsync > batches

Create a batch

Changed on

Use this method to submit many video analysis requests in a single call. Each request creates an analysis task. The response contains one batch identifier and one task identifier per request. Use the batch identifier to check progress and retrieve results.

When to use this method:

  • Run the same analysis settings across many videos.
  • Track a single batch instead of many individual analysis tasks.

Do not use this method for:

  • Single videos that require immediate results. Use the POST method of the /analyze endpoint instead.
  • Background processing of a single video. Use the POST method of the /analyze/tasks endpoint instead.

Retention and retry:

  • Batches expire 24 hours after creation. You can retrieve results for 30 days after creation.
  • If processing does not finish for some items in time, resubmit them in a new batch.
  • An item whose analysis window exceeds 2 hours fails on its own. The error code is video_duration_too_long. The rest of the batch is still submitted.

Limits:

  • Up to 1,000 requests per batch.
  • Up to 2,000 total content hours per batch.
  • Up to 5 active batches per account.
  • The duration limits of the POST method of the /analyze/tasks endpoint apply to each item.
post/analyze/batches

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/analyze/batches
  • Auth: API key in header x-api-key

Request body

model_name'pegasus1.5' required

The video understanding model to use for every item in this batch.

analysis_mode'general' | 'time_based_metadata' required

The analysis mode for every item in this batch.

  • general: Generate text from each video based on the prompt (the prompt field of the item if set, otherwise defaults.prompt). Supports structured JSON output by using json_schema in the response_format.type field.
  • time_based_metadata: Extract timestamped metadata by using segment_definitions in the response_format.type field.

Batches with mixed modes are not supported.

Response

The platform has created the batch and queued an analysis task for each request.

batch_idstring required

The unique identifier of the batch.

status'pending' | 'processing' | 'canceling' | 'canceled' | 'completed' | 'expired' required

The status of a batch. For the meaning of each value, see the Batch statuses section on the The batch object page.

total_itemsinteger required

The number of items submitted in the batch.

created_atstring date-time required

The date and time, in the RFC 3339 format, when the batch was created.

expires_atstring date-time required

The date and time, in the RFC 3339 format, when the batch expires (the created_at field value plus 24 hours). Unfinished items at expiration are canceled. Items that finished before then remain retrievable for 30 days after creation, when the batch and its results are deleted.

Changes

  • 8b021f9a1426Revision changes
    • info

      added the new optional request property ///////

    • info

      added the new optional request property ////////

    • info

      added the new object enum value to the request property ///////

    • info

      added the new object enum value to the request property ////////

    • info

      added the new time_array enum value to the request property //////

    • info

      added the new time_array enum value to the request property ///////

  • b8591e05c0baRevision changes
    • warning

      deleted the header request parameter x-api-key

    • info

      the endpoint scheme security x-api-key was added to the API