For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • TwelveLabs API
    • Introduction
    • Authentication
  • API Reference
    • Manage indexes
    • Upload content
      • Direct uploads
      • Multipart uploads
      • Video indexing tasks
        • The task object
        • POSTCreate a video indexing task
        • GETList video indexing tasks
        • GETRetrieve a video indexing task
        • DELDelete a video indexing task
    • Index content
    • Manage videos
    • Manage entities
    • Any-to-video search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceUpload contentVideo indexing tasks

Create a video indexing task

POST
https://api.twelvelabs.io/v1.3/tasks
POST
/v1.3/tasks
$curl -X POST https://api.twelvelabs.io/v1.3/tasks \
>     -H "x-api-key: <apiKey>" \
>     -H "Content-Type: multipart/form-data" \
>     -F index_id="6298d673f1090f1100476d4c" \
>     -F video_file=@@/Users/john/Documents/01.mp4
1{
2  "_id": "62a1ec6d9ea24f052b971a0f",
3  "video_id": "62a1ec6d9ea24f052b971a0f"
4}
This method creates a video indexing task that uploads and indexes a video in a single operation. <Warning title="Legacy endpoint"> This endpoint bundles two operations (upload and indexing) together. In the next major API release, this endpoint will be removed in favor of a separated workflow: 1. Upload your video using the [`POST /assets`](/v1.3/api-reference/upload-content/direct-uploads/create) endpoint 2. Index the uploaded video using the [`POST /indexes/{index-id}/indexed-assets`](/v1.3/api-reference/index-content/create) endpoint This separation provides better control, reusability of assets, and improved error handling. New implementations should use the new workflow. </Warning> Upload options: - **Local file**: Use the `video_file` parameter. - **Publicly accessible URL**: Use the `video_url` parameter. Your video files must meet requirements based on your workflow: - **Search**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#video-file-requirements). - **Video analysis**: [Pegasus requirements](/v1.3/docs/concepts/models/pegasus#video-file-requirements). - If you want to both search and analyze your videos, the most restrictive requirements apply. - This method allows you to upload files up to 2 GB in size. To upload larger files, use the [Multipart Upload API](/v1.3/api-reference/upload-content/multipart-uploads) <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>
Was this page helpful?
Previous

List video indexing tasks

Next
Built with

This method creates a video indexing task that uploads and indexes a video in a single operation.

Legacy endpoint

This endpoint bundles two operations (upload and indexing) together. In the next major API release, this endpoint will be removed in favor of a separated workflow:

  1. Upload your video using the POST /assets endpoint
  2. Index the uploaded video using the POST /indexes/{index-id}/indexed-assets endpoint

This separation provides better control, reusability of assets, and improved error handling. New implementations should use the new workflow.

Upload options:

  • Local file: Use the video_file parameter.
  • Publicly accessible URL: Use the video_url parameter.

Your video files must meet requirements based on your workflow:

  • Search: Marengo requirements.
  • Video analysis: Pegasus requirements.
  • If you want to both search and analyze your videos, the most restrictive requirements apply.
  • This method allows you to upload files up to 2 GB in size. To upload larger files, use the Multipart Upload API
Note

This endpoint is rate-limited. For details, see the Rate limits page.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Request

Request to upload a video to an index.
index_idstringRequired
The unique identifier of the index to which the video is being uploaded.
video_filefileOptional
Specify this parameter to upload a video from your local file system.
video_urlstringOptional
Specify this parameter to upload a video from a publicly accessible URL.
enable_video_streambooleanOptionalDefaults to true

This parameter indicates if the platform stores the video for streaming. When set to true, the platform stores the video, and you can retrieve its URL by calling the GET method of the /indexes/{index-id}/videos/{video-id} endpoint. You can then use this URL to access the stream over the HLS protocol.

user_metadatastringOptional

Metadata that helps you categorize your videos. You can specify a list of keys and values. Keys must be of type string, and values can be of the following types: string, integer, float, or boolean. Send this value as a JSON-encoded string.

Response

A video indexing task has successfully been created.
_idstring
A string representing the unique identifier of your video indexing task.
video_idstring
A string representing the unique identifier of the video associated with the specified video indexing task.

Errors

400
Bad Request Error