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.

📘

Notes:

• The platform supports uploading video files 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.
• The ability to upload videos from YouTube is no longer supported.

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 API Key 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 at least 480x360 or 360x480, and not exceed 4K.
  • 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. Note: HLS(live streaming) videos can only be uploaded using the API. 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 30 minutes (1800s). 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 audio model option is selected, the video you're uploading must contain an audio track.

Procedure

1. Import the required packages into your application:

   PythonNode.js

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

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

2. Instantiate the SDK client with your API key:

   PythonNode.js

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

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

3. 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")
     PythonNode.js

     task = client.task.create(
       index_id="<YOUR_INDEX_ID>",
       file="<YOUR_VIDEO_FILE>",
       transcription_file="<YOUR_TRANSCRIPTION_FILE>"
     )
     print(f"Task id={task.id}, Video id={task.video_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} Video id=${task.videoId}`);
     

   • 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")
     PythonNode.js

     task = client.task.create(
       index_id="<YOUR_INDEX_ID>",
       url="<YOUR_VIDEO_URL>",
       transcription_url="<YOUR_TRANSCRIPTION_URL>"
     )
     print(f"Task id={task.id}, Video id={task.video_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} Video id=${task.videoId}`);
     

4. 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.
   PythonNode.js

   # 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}`);
   

   
   

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

📘

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.

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.

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
• user_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>",
    user_metadata={
        "views": 12000,
        "downloads": 40000,
        "language": "en-us",
        "country": "USA"
    }
)

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