API ReferenceUpload videos

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.

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, or 9:16.
  • 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.

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

Notes
  • The platform supports video URLs that can play without additional user interaction or custom video players. Ensure your URL points to the raw video file, not a web page containing the video. Links to third-party hosting sites, cloud storage services, or videos requiring extra steps to play are not supported.
  • This endpoint is rate-limited. For details, see the Rate limits page.

Headers

x-api-keystringRequired

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.

Response

A video indexing task has successfully been created.

_idstringOptional

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

video_idstringOptional

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

Errors