Tasks handle the uploading and processing of videos. Because these operations take some time, video uploading and processing are asynchronous.

The platform utilizes two primary types of tasks:

Video indexing tasks: These tasks upload and index videos, making their content accesible to the Search and Generate APIs.
Video embedding tasks: These tasks upload videos and process videos, making their content accessible to the Embed API.

Video indexing tasks

A video indexing task transitions through the following stages, each representing a phase in the platform’s processing:

validating: Ensures the video meets requirements.
pending: Assigns a server to process the video.
queued: Prepares the video for indexing.
indexing: Converts the video into embeddings.
ready: Completes the process, making the video usable.
failed: Indicates an error occurred.

The example code below shows how you can track the progress of a task, checking its status until it’s completed:

1 from twelvelabs import TwelveLabs
2 from twelvelabs.models.task import Task
3 
4 # Initialize the TwelveLabs client with your API key
5 client = TwelveLabs(api_key="<YOUR_API_KEY>")
6 
7 # Upload a video file by creating a video indexing task 
8 task = client.task.create(
9     index_id="<YOUR_INDEX_ID>",
10     file="<YOUR_VIDEO_FILE>"
11 )
12 print(f"Task id={task.id}")
13 
14 # Monitor the task status until the status is ready
15 def on_task_update(task: Task):
16     print(f"  Status={task.status}")
17 
18 task.wait_for_done(sleep_interval=5, callback=on_task_update)
19 
20 if task.status != "ready":
21     raise RuntimeError(f"Indexing failed with status {task.status}")
22 print(f"The unique identifier of your video is {task.video_id}.")

Video embedding tasks

A video embedding task progresses through the following stages:

processing: The platform is creating the embeddings.
ready: Processing is complete. You can now retrieve the embeddings.
failed: The task could not be completed, and the embeddings haven’t been created.

The example code below shows how you can track the progress of a video embedding task, checking its status until it’s completed:

1 from twelvelabs import TwelveLabs
2 from typing import List
3 from twelvelabs.models.embed import EmbeddingsTask, SegmentEmbedding
4 
5 # Initialize the TwelveLabs client with your API key
6 client = TwelveLabs(api_key="<YOUR_API_KEY>")
7 
8 # Upload a video
9 task = client.embed.task.create(model_name="Marengo-retrieval-2.7", video_file="<YOUR_VIDEO_FILE>")
10 print(
11     f"Created task: id={task.id} model_name={task.model_name} status={task.status}")
12   
13 # Monitor the status
14 def on_task_update(task: EmbeddingsTask):
15     print(f"  Status={task.status}")
16 status = task.wait_for_done(sleep_interval=2, callback=on_task_update)
17 print(f"Embedding done: {status}")