Create a video indexing task

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

Upload options:

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

Video requirements

The videos you wish to upload must meet the following requirements:

Video resolution: Must be at least 360x360 and must not exceed 3840x2160.
Aspect ratio: Must be one of 1:1, 4:3, 4:5, 5:4, 16:9, 9:16, or 17:9.
Video and audio formats: Your video files must be encoded in the video and audio formats listed on the FFmpeg Formats Documentation page. For videos in other formats, contact us at support@twelvelabs.io.
Duration: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 4 seconds and 60 minutes (3600s). In a future release, the maximum duration for Pegasus will be 2 hours (7,200 seconds).
File size: Must not exceed 2 GB. If you require different options, contact us at support@twelvelabs.io.
Video URLs: Must be direct links to raw video files that play without user interaction or custom video players (example: https://example.com/videos/sample-video.mp4). Video hosting platforms like YouTube and cloud storage sharing links are not supported.

If both Marengo and Pegasus are enabled for your index, the most restrictive prerequisites will apply.

Note

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

This method creates a video indexing task that uploads and indexes a video. Upload options: - **Local file**: Use the `video_file` parameter. - **Publicly accessible URL**: Use the `video_url` parameter. <Accordion title="Video requirements"> The videos you wish to upload must meet the following requirements: - **Video resolution**: Must be at least 360x360 and must not exceed 3840x2160. - **Aspect ratio**: Must be one of 1:1, 4:3, 4:5, 5:4, 16:9, 9:16, or 17:9. - **Video and audio formats**: Your video files must be encoded in the video and audio formats listed on the [FFmpeg Formats Documentation](https://ffmpeg.org/ffmpeg-formats.html) page. For videos in other formats, contact us at support@twelvelabs.io. - **Duration**: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 4 seconds and 60 minutes (3600s). In a future release, the maximum duration for Pegasus will be 2 hours (7,200 seconds). - **File size**: Must not exceed 2 GB. If you require different options, contact us at support@twelvelabs.io. - **Video URLs**: Must be direct links to raw video files that play without user interaction or custom video players (example: `https://example.com/videos/sample-video.mp4`). Video hosting platforms like YouTube and cloud storage sharing links are not supported. If both Marengo and Pegasus are enabled for your index, the most restrictive prerequisites will apply. </Accordion> <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>

Authentication

x-api-keystring

API Key authentication via header

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.

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`](/v1.3/api-reference/videos/retrieve) method of the `/indexes/{index-id}/videos/{video-id}` endpoint. You can then use this URL to access the stream over the <a href="https://en.wikipedia.org/wiki/HTTP_Live_Streaming" target="_blank">HLS</a> 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.

Response

A video indexing task has successfully been created.

_idstring or null

A string representing the unique identifier of your video indexing task.

video_idstring or null

A string representing the unique identifier of the video associated with the specified video indexing task.

Errors