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.

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 360x360 and must not exceed 3840x2160.
  • Aspect ratio: Must be between 1:1 and 16:9.
  • 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 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.
  • Audio track: If the audio model option is selected, the video you’re uploading must contain an audio track.

Procedure

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

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

1
task = client.task.create(
2
  index_id="<YOUR_INDEX_ID>",
3
  file="<YOUR_VIDEO_FILE>",
4
  transcription_file="<YOUR_TRANSCRIPTION_FILE>"
5
)
6
print(f"Task id={task.id}, Video id={task.video_id}")

1
# Utility function to print the status of a video indexing task
2
def on_task_update(task: Task):
3
    print(f"  Status={task.status}")
4
5
task.wait_for_done(sleep_interval=5, callback=on_task_update)
6
7
if task.status != "ready":
8
raise RuntimeError(f"Indexing failed with status {task.status}")
9
print(f"The unique identifer of your video is {task.video_id}.")

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.

1
client.index.video.update(
2
    index_id="<YOUR_INDEX_ID>,
3
    id="<YOUR_VIDEO_ID>",
4
    user_metadata={
5
        "views": 12000,
6
        "downloads": 40000,
7
        "language": "en-us",
8
        "country": "USA"
9
    }
10
)