Sign in
analyzeAsync > batches

Create a batch

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.

Limits:

  • Up to 1,000 requests per batch.
  • Up to 2,000 total content hours per batch.
  • Up to 5 active batches per account.
post/analyze/batches

Headers

x-api-keystring required

Your API key.

<Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

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 approach 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

Changed in 1 of the 9 revisions of this API.1518

  • fd9d80e384a81518See the full diff
    • ▲

      the defaults/prompt/input_text request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/prompt/media_sources/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/response_format/segment_definitions/items/description request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/response_format/segment_definitions/items/fields/items/description request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/response_format/segment_definitions/items/fields/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/response_format/segment_definitions/items/id request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the defaults/response_format/segment_definitions/items/media_sources/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/prompt/input_text request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/prompt/media_sources/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/response_format/segment_definitions/items/description request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/response_format/segment_definitions/items/fields/items/description request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/response_format/segment_definitions/items/fields/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/response_format/segment_definitions/items/id request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      the requests/items/response_format/segment_definitions/items/media_sources/items/name request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ▲

      added the pattern ^[a-zA-Z0-9_-]{1,64}$ to the request property requests/items/custom_id

      request-property-pattern-added

    • ●

      the defaults/prompt/media_sources/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the defaults/response_format/segment_definitions/items/fields/items/enum/items/ request property's maxLength was set to 100

      request-property-max-length-set

    • ●

      the defaults/response_format/segment_definitions/items/fields/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the defaults/response_format/segment_definitions/items/id request property's maxLength was set to 100

      request-property-max-length-set

    • ●

      the defaults/response_format/segment_definitions/items/media_sources/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the requests/items/prompt/media_sources/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the requests/items/response_format/segment_definitions/items/fields/items/enum/items/ request property's maxLength was set to 100

      request-property-max-length-set

    • ●

      the requests/items/response_format/segment_definitions/items/fields/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the requests/items/response_format/segment_definitions/items/id request property's maxLength was set to 100

      request-property-max-length-set

    • ●

      the requests/items/response_format/segment_definitions/items/media_sources/items/name request property's maxLength was set to 50

      request-property-max-length-set

    • ●

      the defaults/max_tokens request property's max was set to 98304.00

      request-property-max-set

    • ●

      the requests/items/max_tokens request property's max was set to 98304.00

      request-property-max-set

    • ●

      the defaults/max_segment_duration request property's min was set to 2.00

      request-property-min-set

    • ●

      the defaults/max_tokens request property's min was set to 512.00

      request-property-min-set

    • ●

      the defaults/min_segment_duration request property's min was set to 2.00

      request-property-min-set

    • ●

      the requests/items/max_segment_duration request property's min was set to 2.00

      request-property-min-set

    • ●

      the requests/items/max_tokens request property's min was set to 512.00

      request-property-min-set

    • ●

      the requests/items/min_segment_duration request property's min was set to 2.00

      request-property-min-set