> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta.docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server. # Create a batch POST https://api.twelvelabs.io/v1.3/analyze/batches Content-Type: application/json 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`](/v1.3/api-reference/analyze-videos/sync-analysis) method of the `/analyze` endpoint instead. - Background processing of a single video. Use the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) 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`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint apply to each item. Reference: https://beta.docs.twelvelabs.io/api-reference/analyze-videos/batch-analysis/create-batch ## Authentication - `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page. ## Request ### Body (application/json) This endpoint expects a CreateAnalyzeBatchRequest. - `model_name` (enum, required) — The video understanding model to use for every item in this batch. - Allowed values: `pegasus1.5` - `analysis_mode` (enum, 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. - Allowed values: `general`, `time_based_metadata` - `requests` (list of BatchItemRequest, required) — The analysis requests in the batch. Provide 1 to 1,000 requests, with a combined video duration of up to 2,000 hours. - `defaults` (BatchDefaults, optional) — Default values applied to every item that does not override them. Every field is optional. Items in the `requests` array override these values. To override the `prompt` or `response_format` field, provide the full object on the item. You cannot change only some of its nested fields. ## Response ### 201 The platform has created the batch and queued an analysis task for each request. - `batch_id` (string, required) — The unique identifier of the batch. - `status` (enum, required) — The status of a batch. For the meaning of each value, see the [Batch statuses](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object#batch-statuses) section on the **The batch object** page. - Allowed values: `pending`, `processing`, `canceling`, `canceled`, `completed`, `expired` - `total_items` (integer, required) — The number of items submitted in the batch. - `created_at` (string, required) — The date and time, in the RFC 3339 format, when the batch was created. - `expires_at` (string, 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. - `items` (list of CreatedBatchItem, required) — One entry per submitted item. Each entry pairs the unique task identifier generated by the platform with the custom identifier you provided when you created the batch. ## Errors ### 400 Bad Request Error Validation failure. The batch was not created. Possible causes include: - Malformed request bodies, or duplicate values in the `custom_id` field within the batch. - Missing required fields for the chosen analysis mode. - A missing video reference: the `requests.video` field is not provided, or its `type` is not `asset_id`. - A malformed value in the `requests.video.asset_id` field. - `error` (ErrorResponseError, required) ### 404 Not Found Error A referenced asset does not exist, or you cannot access it. The batch was not created. Verify the `requests.video.asset_id` value and that the asset belongs to your account. - `error` (ErrorResponseError, required) ### 409 Conflict Error A referenced asset exists but is not yet in the `ready` state. The batch was not created. Wait for the asset to reach the `ready` state, then resubmit the batch. - `error` (ErrorResponseError, required) ### 429 Too Many Requests Error You already have 5 active batches, or you exceeded the request rate limit. - `error` (ErrorResponseError, required) ### 503 Service Unavailable Error A cross-resource validation check against a downstream service (for example, asset metadata) failed temporarily. The batch was not created. Retry the request. - `error` (ErrorResponseError, required) ### 504 Gateway Timeout Error The server did not finish creating the batch before its processing deadline. The batch was not created. Split the requests across smaller batches and retry. - `error` (ErrorResponseError, required) ## Types ### BatchItemRequest A single analysis request inside a batch. Identify the video in the `video` field. Every other field is optional and overrides the matching field in the `defaults` object. - `video` (BatchVideoContext, required) — Identifies the asset to analyze. - `custom_id` (string, optional) — An optional identifier you set per item when you create the batch. Use this field to map batch results back to records in your system, for example, to correlate each result with the source video in your database. The platform stores this value unchanged. It appears in: * **Batch responses**: the array named `items` in the Create a batch response, and each line returned by the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-results) method of the `/analyze/batches/{batch_id}/results` endpoint. * **Task responses**: each batch request creates an analysis task. The `custom_id` field appears in the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint and the [`GET`](/v1.3/api-reference/analyze-videos/list-async-analysis-tasks) method of the `/analyze/tasks` endpoint. Tasks created as part of a batch do not produce per-task webhook events. **Format**: 1–64 characters. Alphanumeric, hyphens (`-`), and underscores (`_`) only. An empty string is rejected with a `400 Bad Request`. The value must be unique within a batch. Submitting two items with the same value in the `custom_id` field in the same batch returns a `400 Bad Request`. Items without a custom identifier still receive a unique task identifier generated by the platform in results. - `prompt` (BatchPrompt, optional) — A structured prompt with `<@name>` placeholders for referencing images. Not supported when `analysis_mode` is `time_based_metadata`. - `response_format` (AsyncResponseFormat, optional) — 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 `analysis_mode` set to `time_based_metadata`. - `temperature` (double, optional) — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1 - `max_tokens` (integer, optional) — Override the `defaults.max_tokens` value for this item. - `min_segment_duration` (double, optional) — Override the `defaults.min_segment_duration` value for this item. - `max_segment_duration` (double, optional) — Override the `defaults.max_segment_duration` value for this item. - `start_time` (double, optional) — Override the `defaults.start_time` value for this item. - `end_time` (double, optional) — Override the `defaults.end_time` value for this item. ### BatchDefaults Default values applied to every item that does not override them. Every field is optional. Items in the `requests` array override these values. To override the `prompt` or `response_format` field, provide the full object on the item. You cannot change only some of its nested fields. - `prompt` (BatchPrompt, optional) — A structured prompt with `<@name>` placeholders for referencing images. Not supported when `analysis_mode` is `time_based_metadata`. - `response_format` (AsyncResponseFormat, optional) — 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 `analysis_mode` set to `time_based_metadata`. - `temperature` (double, optional) — Controls the randomness of the text output. **Default:** 0.2 **Min:** 0 **Max:** 1 - `max_tokens` (integer, optional) — The maximum number of tokens to generate per item. The allowed range depends on the analysis mode (see the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint for the per-mode table). - `min_segment_duration` (double, optional) — Minimum duration for each extracted segment, in seconds. Applies only when the `analysis_mode` field is `time_based_metadata`. **Min:** 2 - `max_segment_duration` (double, optional) — Maximum duration for each extracted segment, in seconds. Must be greater than or equal to the `min_segment_duration` field. Applies only when the `analysis_mode` field is `time_based_metadata`. **Min:** 2 - `start_time` (double, optional) — Start of the analysis window, in seconds, applied to every item. Use with `end_time` to analyze only a portion of each video. * If omitted, defaults to `0`. * Must be less than `end_time`. * The window (`end_time - start_time`) must be at least 1 second and at most 2 hours for each item. Each 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`. - `end_time` (double, optional) — End of the analysis window, in seconds, applied to every item. Use with `start_time` to analyze only a portion of each video. * If omitted, defaults to the video duration. * Must be greater than `start_time`. * The window (`end_time - start_time`) must be at least 1 second and at most 2 hours for each item. Each 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`. ### CreatedBatchItem One submitted item in the Create a batch response. - `task_id` (string, required) — The unique task identifier generated by the platform for this item. Use this value with the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint to retrieve the task's status and results. - `custom_id` (string, required, nullable) — The custom identifier you provided when you created the batch. If you did not provide one, this field is `null`. ### ErrorResponseError - `code` (string, required) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details. - `message` (string, required) — A human-readable string describing the error, intended to be suitable for display in a user interface. - `details` (map from string to any, optional) — Additional error details (optional) ### BatchVideoContext Identifies the asset to analyze. - `type` (enum, required) — Set this field to `asset_id` to indicate that you're providing the video as an asset. - Allowed values: `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. ### BatchPrompt A structured prompt with `<@name>` placeholders for referencing images. Not supported when `analysis_mode` is `time_based_metadata`. - `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?"`). This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). - `media_sources` (list of SMEMediaSource, optional) — Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources. ### 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 `analysis_mode` set to `time_based_metadata`. - `type` (enum, 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 `analysis_mode` set to `time_based_metadata`. - Allowed values: `json_schema`, `segment_definitions` - `json_schema` (AsyncResponseFormatJsonSchema, optional) — 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` **Supported constraints** | Type | Supported keywords | Notes | | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).- `exclusiveMaximum`: Sets the highest allowed value (exclusive).- `minimum`: Sets the lowest allowed value (inclusive).- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas.- `required`: Specifies mandatory properties.See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.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** Declare a property as `{"type": "timestamp", "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.` * Inside an array: `properties..items.properties.` 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..format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** The `start_time` and `end_time` properties 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 `finish_reason` field to verify your JSON response is complete: * When `finish_reason` is `stop`, the generation completed normally, and the JSON is valid and complete. * When `finish_reason` is `length`, the generation reached the maximum response length or the context window. The output may be truncated and fail to parse. - `segment_definitions` (list of SegmentDefinition, optional) — 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. - `segment_time_format` (enum, optional, default: seconds) — 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`. 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`). For a `time_array` field, it also formats the `start_time` and `end_time` of each event inside the segment. Custom `timestamp` fields always use their own format, regardless of the value of this field. - Allowed values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff` ### SMEMediaSource A reference image that provides visual context for segment identification. Provide exactly one of `url`, `asset_id`, or `base64_string`. - `name` (string, required) — A descriptive name for this media source. - `media_type` (enum, required) — The media type. Only `image` is available. - Allowed values: `image` - `url` (string, optional) — A publicly accessible HTTPS URL of the image. - `asset_id` (string, optional) — The unique identifier of an uploaded asset. - `base64_string` (string, optional) — Base64-encoded image data. The maximum decoded size is 32 MB. ### 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` **Supported constraints** | Type | Supported keywords | Notes | | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `integer` | `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`. | - `maximum`: Sets the highest allowed value (inclusive).- `exclusiveMaximum`: Sets the highest allowed value (exclusive).- `minimum`: Sets the lowest allowed value (inclusive).- `exclusiveMinimum`: Sets the lowest allowed value (exclusive).These constraints are supported only for the `integer` type. | | `string` | `pattern`, `format` | - `pattern`: A regular expression that the string must match.- `format`: Validates predefined formats. It accepts the following values: `uuid`, `date-time`, `date`, and `time`.See string limitations below. | | `object` | `properties`, `required` | - `properties`: Defines object properties and their schemas.- `required`: Specifies mandatory properties.See object limitations below. | | `array` | `items`, `minItems` | `minItems` accepts only `0` or `1`.See array limitations below. | | `timestamp` | `format` | `format` (required): Sets the output format. Accepted values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff`.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** Declare a property as `{"type": "timestamp", "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.` * Inside an array: `properties..items.properties.` 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..format: format is required for timestamp type; allowed values: seconds, hh:mm:ss, hh:mm:ss.fff ``` **Reserved property names (`start_time` / `end_time`)** The `start_time` and `end_time` properties 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 `finish_reason` field to verify your JSON response is complete: * When `finish_reason` is `stop`, the generation completed normally, and the JSON is valid and complete. * When `finish_reason` is `length`, the generation reached the maximum response length or the context window. The output may be truncated and fail to parse. ### SegmentDefinition Defines a type of segment to extract from the video. - `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` (list of SegmentField, optional) — Custom fields to extract for each segment instance. Set the `type` field of an item to the `time_array` value to extract a list of events inside each segment. - `media_sources` (list of SMEMediaSource, optional) — Reference images that help the model identify segments. Maximum 4 sources. - `time_ranges` (list of AnalyzeTimeRange, optional) — Time windows that limit segment extraction to specific parts of the video. Only supported when `analysis_mode` is set to `time_based_metadata`. * 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. ### SegmentField A custom field to extract for each segment. **Timestamp fields** Set `type` to `timestamp` and provide a `format` to control the format of the returned value on each segment. See the `format` property for supported values. Each segment includes automatic `start_time` and `end_time` keys (floats in seconds) that mark the segment boundary. These names, along with `metadata`, are reserved and cannot be used as the name of a segment field or as the name of a field inside a `time_array` item. - `name` (string, required) — The name of the field. - `type` (enum, required) — The data type of the field. When set to `timestamp`, the `format` property is required and controls the format of the returned value. When set to the `time_array` value, the field extracts a list of events inside each segment. Requires the `items.type` field to be `object` and a non-empty `items.fields` list. Requires Pegasus 1.6. Any other model rejects `time_array` as an invalid type and lists only the types it accepts. The `/analyze/batches` endpoint does not accept Pegasus 1.6, so it does not accept `time_array` either. - Allowed values: `string`, `boolean`, `number`, `integer`, `array`, `timestamp`, `time_array` - `description` (string, required) — Instructions that guide the model on what this field should contain and how to extract it from the video. - `format` (enum, optional) — 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. - Allowed values: `seconds`, `hh:mm:ss`, `hh:mm:ss.fff` - `enum` (list of string, optional) — Allowed values for this field. Maximum 100 values. Not supported when `type` is `timestamp`. - `items` (SegmentFieldItems, optional) — Required when `type` is `array` or `time_array`. For `array`, specifies the type of array elements. For `time_array`, set it to `{"type": "object", "fields": [...]}`. Not supported when `type` is `timestamp`. ### AnalyzeTimeRange A time window within the video, expressed in seconds. - `start_time` (double, required) — The start of the window, as an absolute timestamp in seconds, based on the internal metadata of the video. 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` (double, required) — The end of the window, as an absolute timestamp in seconds, based on the internal metadata of the video. 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`. ### SegmentFieldItems 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. - `type` (enum, required) — The item type. For an `array` field, use one of the scalar types (`string`, `number`, `boolean`, `integer`). For a `time_array` field, use `object` and declare the per-event schema in the `fields` array. Setting `object` as the `type` value on a plain `array` field returns a `400` error. Setting the `fields` array on a plain `array` field also returns a `400` error. - Allowed values: `string`, `number`, `boolean`, `integer`, `object` - `fields` (list of TimeArrayItemField, optional) — The fields to extract from each event. Required when the `type` of the parent field is `time_array`, with at least one entry. Not permitted on any other field type. ### TimeArrayItemField 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. - `name` (string, required) — The name of the field inside each event object. Must be unique within the item. The names `start_time`, `end_time`, and `metadata` are reserved and rejected with a `400` error. - `type` (enum, required) — The data type of this field. It does not accept `timestamp` or `time_array`. When set to the `array` value, the `items` object is required. - Allowed values: `string`, `boolean`, `number`, `integer`, `array` - `description` (string, required) — Instructions that guide the model on what this field should contain in each event. - `enum` (list of string, optional) — Allowed values for this field. Maximum 100 values. Only supported when `type` is `string`; any other type returns a `400` error. - `items` (TimeArrayItemFieldItems, optional) — The element type for an `array` field. Required when `type` is `array`; not supported on any other type. ### TimeArrayItemFieldItems The element type for an `array` field. Required when `type` is `array`; not supported on any other type. - `type` (enum, required) — The type of the array elements. It must be a scalar (`string`, `number`, `boolean`, or `integer`). - Allowed values: `string`, `number`, `boolean`, `integer` ## Examples ### analyzeAsync_batches_create_example **Response** ```json { "batch_id": "68f4ddaf8aaa60d33df0e800", "status": "pending", "total_items": 3, "created_at": "2026-05-15T10:00:00Z", "expires_at": "2026-05-16T10:00:00Z", "items": [ { "task_id": "68f4ddaf8aaa60d33df0e900", "custom_id": "summary-001" }, { "task_id": "68f4ddaf8aaa60d33df0e901", "custom_id": "summary-002" }, { "task_id": "68f4ddaf8aaa60d33df0e902", "custom_id": "action-003" } ] } ``` **SDK Code** ```python analyzeAsync_batches_create_example import requests url = "https://api.twelvelabs.io/v1.3/analyze/batches" headers = {"x-api-key": ""} response = requests.post(url, headers=headers) print(response.json()) ``` ```javascript analyzeAsync_batches_create_example const url = 'https://api.twelvelabs.io/v1.3/analyze/batches'; const options = {method: 'POST', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go analyzeAsync_batches_create_example package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/analyze/batches" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby analyzeAsync_batches_create_example require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/analyze/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java analyzeAsync_batches_create_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.twelvelabs.io/v1.3/analyze/batches") .header("x-api-key", "") .asString(); ``` ```php analyzeAsync_batches_create_example request('POST', 'https://api.twelvelabs.io/v1.3/analyze/batches', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp analyzeAsync_batches_create_example using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift analyzeAsync_batches_create_example import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### General analysis with shared defaults **Request** ```json { "model_name": "pegasus1.5", "analysis_mode": "general", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "summary-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "summary-002" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4e" }, "custom_id": "action-003", "prompt": { "input_text": "List all action items discussed." } } ], "defaults": { "prompt": { "input_text": "Generate a 3-sentence executive summary of this video." }, "temperature": 0.2, "max_tokens": 4096 } } ``` **Response** ```json { "batch_id": "68f4ddaf8aaa60d33df0e800", "status": "pending", "total_items": 3, "created_at": "2026-05-15T10:00:00Z", "expires_at": "2026-05-16T10:00:00Z", "items": [ { "task_id": "68f4ddaf8aaa60d33df0e900", "custom_id": "summary-001" }, { "task_id": "68f4ddaf8aaa60d33df0e901", "custom_id": "summary-002" }, { "task_id": "68f4ddaf8aaa60d33df0e902", "custom_id": "action-003" } ] } ``` **SDK Code** ```python General analysis with shared defaults import requests url = "https://api.twelvelabs.io/v1.3/analyze/batches" payload = { "model_name": "pegasus1.5", "analysis_mode": "general", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "summary-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "summary-002" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4e" }, "custom_id": "action-003", "prompt": { "input_text": "List all action items discussed." } } ], "defaults": { "prompt": { "input_text": "Generate a 3-sentence executive summary of this video." }, "temperature": 0.2, "max_tokens": 4096 } } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript General analysis with shared defaults const url = 'https://api.twelvelabs.io/v1.3/analyze/batches'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"model_name":"pegasus1.5","analysis_mode":"general","requests":[{"video":{"type":"asset_id","asset_id":"6298d673f1090f1100476d4c"},"custom_id":"summary-001"},{"video":{"type":"asset_id","asset_id":"6298d673f1090f1100476d4d"},"custom_id":"summary-002"},{"video":{"type":"asset_id","asset_id":"6298d673f1090f1100476d4e"},"custom_id":"action-003","prompt":{"input_text":"List all action items discussed."}}],"defaults":{"prompt":{"input_text":"Generate a 3-sentence executive summary of this video."},"temperature":0.2,"max_tokens":4096}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go General analysis with shared defaults package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/analyze/batches" payload := strings.NewReader("{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"general\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"summary-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"summary-002\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4e\"\n },\n \"custom_id\": \"action-003\",\n \"prompt\": {\n \"input_text\": \"List all action items discussed.\"\n }\n }\n ],\n \"defaults\": {\n \"prompt\": {\n \"input_text\": \"Generate a 3-sentence executive summary of this video.\"\n },\n \"temperature\": 0.2,\n \"max_tokens\": 4096\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby General analysis with shared defaults require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/analyze/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"general\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"summary-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"summary-002\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4e\"\n },\n \"custom_id\": \"action-003\",\n \"prompt\": {\n \"input_text\": \"List all action items discussed.\"\n }\n }\n ],\n \"defaults\": {\n \"prompt\": {\n \"input_text\": \"Generate a 3-sentence executive summary of this video.\"\n },\n \"temperature\": 0.2,\n \"max_tokens\": 4096\n }\n}" response = http.request(request) puts response.read_body ``` ```java General analysis with shared defaults import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.twelvelabs.io/v1.3/analyze/batches") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"general\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"summary-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"summary-002\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4e\"\n },\n \"custom_id\": \"action-003\",\n \"prompt\": {\n \"input_text\": \"List all action items discussed.\"\n }\n }\n ],\n \"defaults\": {\n \"prompt\": {\n \"input_text\": \"Generate a 3-sentence executive summary of this video.\"\n },\n \"temperature\": 0.2,\n \"max_tokens\": 4096\n }\n}") .asString(); ``` ```php General analysis with shared defaults request('POST', 'https://api.twelvelabs.io/v1.3/analyze/batches', [ 'body' => '{ "model_name": "pegasus1.5", "analysis_mode": "general", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "summary-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "summary-002" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4e" }, "custom_id": "action-003", "prompt": { "input_text": "List all action items discussed." } } ], "defaults": { "prompt": { "input_text": "Generate a 3-sentence executive summary of this video." }, "temperature": 0.2, "max_tokens": 4096 } }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp General analysis with shared defaults using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"general\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"summary-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"summary-002\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4e\"\n },\n \"custom_id\": \"action-003\",\n \"prompt\": {\n \"input_text\": \"List all action items discussed.\"\n }\n }\n ],\n \"defaults\": {\n \"prompt\": {\n \"input_text\": \"Generate a 3-sentence executive summary of this video.\"\n },\n \"temperature\": 0.2,\n \"max_tokens\": 4096\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift General analysis with shared defaults import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "model_name": "pegasus1.5", "analysis_mode": "general", "requests": [ [ "video": [ "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" ], "custom_id": "summary-001" ], [ "video": [ "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" ], "custom_id": "summary-002" ], [ "video": [ "type": "asset_id", "asset_id": "6298d673f1090f1100476d4e" ], "custom_id": "action-003", "prompt": ["input_text": "List all action items discussed."] ] ], "defaults": [ "prompt": ["input_text": "Generate a 3-sentence executive summary of this video."], "temperature": 0.2, "max_tokens": 4096 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Video segmentation with shared segment definitions **Request** ```json { "model_name": "pegasus1.5", "analysis_mode": "time_based_metadata", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "ep-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "ep-002" } ], "defaults": { "response_format": { "type": "segment_definitions", "segment_definitions": [ { "id": "product_moments", "description": "Moments where a person holds <@product> while speaking to the camera.", "fields": [ { "name": "segment_title", "type": "string", "description": "A short headline for this moment" }, { "name": "product_visibility", "type": "string", "description": "How prominently the product appears in this segment", "enum": [ "FULL", "PARTIAL", "BACKGROUND" ] } ], "media_sources": [ { "name": "product", "media_type": "image", "url": "https://example.com/product.jpg" } ] } ] }, "temperature": 0, "max_tokens": 4096, "min_segment_duration": 2 } } ``` **Response** ```json { "batch_id": "68f4ddaf8aaa60d33df0e800", "status": "pending", "total_items": 3, "created_at": "2026-05-15T10:00:00Z", "expires_at": "2026-05-16T10:00:00Z", "items": [ { "task_id": "68f4ddaf8aaa60d33df0e900", "custom_id": "summary-001" }, { "task_id": "68f4ddaf8aaa60d33df0e901", "custom_id": "summary-002" }, { "task_id": "68f4ddaf8aaa60d33df0e902", "custom_id": "action-003" } ] } ``` **SDK Code** ```python Video segmentation with shared segment definitions import requests url = "https://api.twelvelabs.io/v1.3/analyze/batches" payload = { "model_name": "pegasus1.5", "analysis_mode": "time_based_metadata", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "ep-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "ep-002" } ], "defaults": { "response_format": { "type": "segment_definitions", "segment_definitions": [ { "id": "product_moments", "description": "Moments where a person holds <@product> while speaking to the camera.", "fields": [ { "name": "segment_title", "type": "string", "description": "A short headline for this moment" }, { "name": "product_visibility", "type": "string", "description": "How prominently the product appears in this segment", "enum": ["FULL", "PARTIAL", "BACKGROUND"] } ], "media_sources": [ { "name": "product", "media_type": "image", "url": "https://example.com/product.jpg" } ] } ] }, "temperature": 0, "max_tokens": 4096, "min_segment_duration": 2 } } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Video segmentation with shared segment definitions const url = 'https://api.twelvelabs.io/v1.3/analyze/batches'; const options = { method: 'POST', headers: {'x-api-key': '', 'Content-Type': 'application/json'}, body: '{"model_name":"pegasus1.5","analysis_mode":"time_based_metadata","requests":[{"video":{"type":"asset_id","asset_id":"6298d673f1090f1100476d4c"},"custom_id":"ep-001"},{"video":{"type":"asset_id","asset_id":"6298d673f1090f1100476d4d"},"custom_id":"ep-002"}],"defaults":{"response_format":{"type":"segment_definitions","segment_definitions":[{"id":"product_moments","description":"Moments where a person holds <@product> while speaking to the camera.","fields":[{"name":"segment_title","type":"string","description":"A short headline for this moment"},{"name":"product_visibility","type":"string","description":"How prominently the product appears in this segment","enum":["FULL","PARTIAL","BACKGROUND"]}],"media_sources":[{"name":"product","media_type":"image","url":"https://example.com/product.jpg"}]}]},"temperature":0,"max_tokens":4096,"min_segment_duration":2}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Video segmentation with shared segment definitions package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/analyze/batches" payload := strings.NewReader("{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"time_based_metadata\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"ep-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"ep-002\"\n }\n ],\n \"defaults\": {\n \"response_format\": {\n \"type\": \"segment_definitions\",\n \"segment_definitions\": [\n {\n \"id\": \"product_moments\",\n \"description\": \"Moments where a person holds <@product> while speaking to the camera.\",\n \"fields\": [\n {\n \"name\": \"segment_title\",\n \"type\": \"string\",\n \"description\": \"A short headline for this moment\"\n },\n {\n \"name\": \"product_visibility\",\n \"type\": \"string\",\n \"description\": \"How prominently the product appears in this segment\",\n \"enum\": [\n \"FULL\",\n \"PARTIAL\",\n \"BACKGROUND\"\n ]\n }\n ],\n \"media_sources\": [\n {\n \"name\": \"product\",\n \"media_type\": \"image\",\n \"url\": \"https://example.com/product.jpg\"\n }\n ]\n }\n ]\n },\n \"temperature\": 0,\n \"max_tokens\": 4096,\n \"min_segment_duration\": 2\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Video segmentation with shared segment definitions require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/analyze/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"time_based_metadata\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"ep-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"ep-002\"\n }\n ],\n \"defaults\": {\n \"response_format\": {\n \"type\": \"segment_definitions\",\n \"segment_definitions\": [\n {\n \"id\": \"product_moments\",\n \"description\": \"Moments where a person holds <@product> while speaking to the camera.\",\n \"fields\": [\n {\n \"name\": \"segment_title\",\n \"type\": \"string\",\n \"description\": \"A short headline for this moment\"\n },\n {\n \"name\": \"product_visibility\",\n \"type\": \"string\",\n \"description\": \"How prominently the product appears in this segment\",\n \"enum\": [\n \"FULL\",\n \"PARTIAL\",\n \"BACKGROUND\"\n ]\n }\n ],\n \"media_sources\": [\n {\n \"name\": \"product\",\n \"media_type\": \"image\",\n \"url\": \"https://example.com/product.jpg\"\n }\n ]\n }\n ]\n },\n \"temperature\": 0,\n \"max_tokens\": 4096,\n \"min_segment_duration\": 2\n }\n}" response = http.request(request) puts response.read_body ``` ```java Video segmentation with shared segment definitions import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.twelvelabs.io/v1.3/analyze/batches") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"time_based_metadata\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"ep-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"ep-002\"\n }\n ],\n \"defaults\": {\n \"response_format\": {\n \"type\": \"segment_definitions\",\n \"segment_definitions\": [\n {\n \"id\": \"product_moments\",\n \"description\": \"Moments where a person holds <@product> while speaking to the camera.\",\n \"fields\": [\n {\n \"name\": \"segment_title\",\n \"type\": \"string\",\n \"description\": \"A short headline for this moment\"\n },\n {\n \"name\": \"product_visibility\",\n \"type\": \"string\",\n \"description\": \"How prominently the product appears in this segment\",\n \"enum\": [\n \"FULL\",\n \"PARTIAL\",\n \"BACKGROUND\"\n ]\n }\n ],\n \"media_sources\": [\n {\n \"name\": \"product\",\n \"media_type\": \"image\",\n \"url\": \"https://example.com/product.jpg\"\n }\n ]\n }\n ]\n },\n \"temperature\": 0,\n \"max_tokens\": 4096,\n \"min_segment_duration\": 2\n }\n}") .asString(); ``` ```php Video segmentation with shared segment definitions request('POST', 'https://api.twelvelabs.io/v1.3/analyze/batches', [ 'body' => '{ "model_name": "pegasus1.5", "analysis_mode": "time_based_metadata", "requests": [ { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" }, "custom_id": "ep-001" }, { "video": { "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" }, "custom_id": "ep-002" } ], "defaults": { "response_format": { "type": "segment_definitions", "segment_definitions": [ { "id": "product_moments", "description": "Moments where a person holds <@product> while speaking to the camera.", "fields": [ { "name": "segment_title", "type": "string", "description": "A short headline for this moment" }, { "name": "product_visibility", "type": "string", "description": "How prominently the product appears in this segment", "enum": [ "FULL", "PARTIAL", "BACKGROUND" ] } ], "media_sources": [ { "name": "product", "media_type": "image", "url": "https://example.com/product.jpg" } ] } ] }, "temperature": 0, "max_tokens": 4096, "min_segment_duration": 2 } }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp Video segmentation with shared segment definitions using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/analyze/batches"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"model_name\": \"pegasus1.5\",\n \"analysis_mode\": \"time_based_metadata\",\n \"requests\": [\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4c\"\n },\n \"custom_id\": \"ep-001\"\n },\n {\n \"video\": {\n \"type\": \"asset_id\",\n \"asset_id\": \"6298d673f1090f1100476d4d\"\n },\n \"custom_id\": \"ep-002\"\n }\n ],\n \"defaults\": {\n \"response_format\": {\n \"type\": \"segment_definitions\",\n \"segment_definitions\": [\n {\n \"id\": \"product_moments\",\n \"description\": \"Moments where a person holds <@product> while speaking to the camera.\",\n \"fields\": [\n {\n \"name\": \"segment_title\",\n \"type\": \"string\",\n \"description\": \"A short headline for this moment\"\n },\n {\n \"name\": \"product_visibility\",\n \"type\": \"string\",\n \"description\": \"How prominently the product appears in this segment\",\n \"enum\": [\n \"FULL\",\n \"PARTIAL\",\n \"BACKGROUND\"\n ]\n }\n ],\n \"media_sources\": [\n {\n \"name\": \"product\",\n \"media_type\": \"image\",\n \"url\": \"https://example.com/product.jpg\"\n }\n ]\n }\n ]\n },\n \"temperature\": 0,\n \"max_tokens\": 4096,\n \"min_segment_duration\": 2\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Video segmentation with shared segment definitions import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "model_name": "pegasus1.5", "analysis_mode": "time_based_metadata", "requests": [ [ "video": [ "type": "asset_id", "asset_id": "6298d673f1090f1100476d4c" ], "custom_id": "ep-001" ], [ "video": [ "type": "asset_id", "asset_id": "6298d673f1090f1100476d4d" ], "custom_id": "ep-002" ] ], "defaults": [ "response_format": [ "type": "segment_definitions", "segment_definitions": [ [ "id": "product_moments", "description": "Moments where a person holds <@product> while speaking to the camera.", "fields": [ [ "name": "segment_title", "type": "string", "description": "A short headline for this moment" ], [ "name": "product_visibility", "type": "string", "description": "How prominently the product appears in this segment", "enum": ["FULL", "PARTIAL", "BACKGROUND"] ] ], "media_sources": [ [ "name": "product", "media_type": "image", "url": "https://example.com/product.jpg" ] ] ] ] ], "temperature": 0, "max_tokens": 4096, "min_segment_duration": 2 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/analyze/batches")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```