Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • TwelveLabs API
    • Introduction
    • Authentication
    • Typical workflows
  • API Reference
    • Manage indexes
    • Upload videos
    • Manage videos
    • Any-to-video search
    • Create video embeddings
    • Create text, image, and audio embeddings
    • Analyze videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceUpload videos

POST
https://api.twelvelabs.io/v1.3/tasks
POST
/v1.3/tasks
1curl -X POST https://api.twelvelabs.io/v1.3/tasks \
2     -H "x-api-key: <apiKey>" \
3     -H "Content-Type: multipart/form-data" \
4     -F index_id="6298d673f1090f1100476d4c" \
5     -F video_file=@@/Users/john/Documents/01.mp4
Try it
200Successful
1{
2  "_id": "62a1ec6d9ea24f052b971a0f",
3  "video_id": "62a1ec6d9ea24f052b971a0f"
4}
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. 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>
Create a video indexing task

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`](/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

Specify this parameter to upload a video from your local file system.
Specify this parameter to upload a video from a publicly accessible URL.
A video indexing task has successfully been created.

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.

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