This guide shows how you can upload a video file to the platform. The platform offers the following options for uploading single videos:

Upload from the local file system: Use this option to upload a single video file from the local file system.
Upload from a direct URL: Use this option to upload a video file from a publicly accessible URL. The platform will retrieve the file directly from the specified URL, so your application doesn't have to store the video locally and upload it.
Upload from external providers: Use this option to upload videos from external platforms by retrieving the video directly from the specified source. Currently, only YouTube is supported, but Twelve Labs will add support for additional providers in the future.

Prerequisites

You’re familiar with the concepts described on the Platform overview page.
You have an API key. To retrieve your API key, navigate to the Dashboard page and log in with your credentials. Then, select the Copy icon to the right of your API key to copy it to your clipboard.
You’ve already created an index.
The video you wish to upload must meet the following requirements:
- Video resolution: Must be greater or equal than 360p and less or equal than 4K. For consistent search results, Twelve Labs recommends you upload 360p videos.
- Video and audio formats: The video files you wish to upload must be encoded in the video and audio formats listed on the FFmpeg Formats Documentation page. For videos in other formats, contact us at [email protected].
- Duration: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 4 seconds and 20 minutes (1200s). 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 [email protected].
- Audio track: If the conversation engine option is selected, the video you're uploading must contain an audio track.

Procedure

Import the required packages into your application:

from twelvelabs import TwelveLabs
from twelvelabs.models.task import Task

import { TwelveLabs, Task } from 'twelvelabs-js';

Instantiate the SDK client with your API key:

client = TwelveLabs(api_key="<YOUR_API_KEY>")

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

Depending on your use case:
- To upload a video from the local file system, invoke the create method of the task object with the following parameters:
  - index_id: A string representing the unique identifier of the index to which you want to upload your video.
  - file: A string representing the path to your video file (example: "/videos/01.mp4").
  - (Optional)transcription_file: A string representing the path to your transcription file (example: "/videos/01.srt")
```
task = client.task.create(
  index_id="<YOUR_INDEX_ID>",
  file="<YOUR_VIDEO_FILE>",
  transcription_file="<YOUR_TRANSCRIPTION_FILE>"
)
print(f"Task id={task.id}")
```
```
const task = await client.task.create({
  indexId: '<YOUR_INDEX_ID>',
  file: '<YOUR_VIDEO_FILE>',
  transcriptionFile: '<YOUR_TRANSCRIPTION_FILE>'),
});
console.log(`Task id=${task.id}`);
```
- To upload a video from a direct URL, invoke the create method of the task object with the following parameters:
  - index_id: A string representing the unique identifier of the index to which you want to upload your video.
  - url: A string representing the URL of the video that you want to upload (example: "https://twelvelabs-docs-assets.s3.us-west-2.amazonaws.com/sample_videos/01.mp4").
  - (Optional) transcription_url: A string representing the URL of your transcription file (example: "https://twelvelabs-docs-assets.s3.us-west-2.amazonaws.com/sample_videos/01.srt")
```
task = client.task.create(
  index_id="<YOUR_INDEX_ID>",
  url="<YOUR_VIDEO_URL>",
  transcription_url="<YOUR_TRANSCRIPTION_URL>"
)
print(f"Task id={task.id}")
```
```
const task = await client.task.create({
  indexId: '<YOUR_INDEX_ID>',
  url: '<YOUR_VIDEO_URL>',
  transcriptionUrl: '<YOUR_TRANSCRIPTION_URL>',
});
console.log(`Task id=${task.id}`);
```
- To upload a video from an external provider, invoke the external_provider method of the task object with the following parameters:
  - index_id: A string representing the unique identifier of the index to which you want to upload your video.
  - url: A string representing the URL of the video that you want to upload (example: "https://www.youtube.com/watch?v=PZ0EAJGQGQI&t=5s").
```
task = client.task.external_provider(
  index_id="<YOUR_INDEX_ID>",
  url="<YOUR_VIDEO_URL>"
)
print(f"Task id={task.id}")
```
```
const task = await client.task.externalProvider(
  '<YOUR_INDEX_ID>',
  '<YOUR_VIDEO_URL>'
);
console.log(`Task id=${task.id}`);
```
(Optional) The Twelve Labs Video Understanding Platform requires some time to index videos. You can search or summarize your videos only after the indexing process is complete. To monitor the indexing process, call the wait_for_done method of the task object with the following parameters:
- sleep_interval: A number specifying the time interval, in seconds, between successive status checks. In this example, the method checks the status every five seconds. Adjust this value to control how frequently the method checks the status.
- callback: A callback function that the SDK executes each time it checks the status. In this example, on_task_update is the callback function. Note that the callback function takes a parameter of type Task. Use this parameter to display the status of your video indexing task.
```
# Utility function to print the status of a video indexing task
def on_task_update(task: Task):
      print(f"  Status={task.status}")

task.wait_for_done(sleep_interval=5, callback=on_task_update)

if task.status != "ready":
  raise RuntimeError(f"Indexing failed with status {task.status}")
print(f"The unique identifer of your video is {task.video_id}.")
```
```
await task.waitForDone(500, (task: Task) => {
  console.log(`  Status=${task.status}`);
});

if (task.status !== 'ready') {
  throw new Error(`Indexing failed with status ${task.status}`);
}
console.log(`The unique identifer of your video is ${task.videoId}`);
```
📘
Notes
- For details about the possible statuses, see the Tasks page.
- You can also use webhooks to monitor the status of the indexing process. For details, see the Webhooks section.
Once a video has been successfully uploaded and indexed, the task object contains, among other information, a field named video_id, representing the unique identifier of your video. For a description of each field in the request and response, see the Create a video indexing task page.

Provide custom metadata

Metadata includes technical and contextual information about each video uploaded to the platform. By default, all the videos have the following metadata associated with them:

duration: The duration of the video, expressed in seconds
filename: The filename
fps: The number of frames per second
height: The height of the video
size: The size of the video file, expressed in KB
video_title: The title of the video (defaults to the file name)
width: The width of the video

Custom metadata allows you to add more data to your videos, providing more detailed, specialized, or context-specific information. You can use custom metadata to filter search results or videos.

Note the following about adding custom metadata to your videos:

You cannot override any of the predefined metadata
The values you provide must be of the following types: string, integer, float or boolean. If you want to store other types of data such as objects or arrays, you must convert your data into string values.

Once the platform has finished indexing your videos, you can provide custom metadata by invoking the update method of the index.video object with the following parameters:

index_id: A string representing the unique identifier of the index containing the video for which you want to provide custom metadata.
id: A string representing the unique identifier of the video
metadata: A dictionary containing your custom metadata. In this example, the metadata dictionary has four keys: views, downloads, language and country. The views and downloads keys are integers, and thecreation_date and country keys are strings.

client.index.video.update(
    index_id="<YOUR_INDEX_ID>,
    id="<YOUR_VIDEO_ID>",
    metadata={
        "views": 12000,
        "downloads": 40000,
        "language": "en-us",
        "country": "USA"
    }
)

client.index.video.update(
  '<YOUR_INDEX_ID>',
  '<YOUR_VIDEO_ID>', 
  {
    metadata: {
      views: 12000,
      downloads: 40000,
      language: 'en-us',
      country: 'USA',
    },
  },
);

Prerequisites

Procedure

📘Notes

Provide custom metadata

📘
Notes