A video indexing task represents a request to upload and index a video. The TasksWrapper class provides methods to manage your video indexing tasks.

Methods

Create a video indexing task

Description: This method creates a new video indexing task that uploads and indexes a video.

Function signature and example:

1
create(request: TwelvelabsApi.TasksCreateRequest, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.TasksCreateResponse>;

The TasksCreateRequest interface defines the parameters for creating a new video indexing task:

Return value: Returns a Promise that resolves to a TasksCreateResponse instance.

The TasksCreateResponse interface contains the following properties:

API Reference: Create a video indexing task.

Retrieve a video indexing task

Description: This method retrieves the details of a specific video indexing task.

Function signature and example:

1
retrieve(taskId: string, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.TasksRetrieveResponse>;

Parameters:

Return value: Returns a Promise that resolves to a TasksRetrieveResponse instance representing the retrieved video indexing task..

The TasksRetrieveResponse interface extends VideoIndexingTask and contains the following properties:

The VideoIndexingTaskSystemMetadata interface contains the following properties:

The HlsObject interface contains the following properties:

API Reference: Retrieve a video indexing task.

Wait for a video indexing task to complete

Description: This method waits until a video indexing task is completed. It checks the task status at regular intervals by retrieving its details. If you provide a callback function, the method calls it after each status check with the current task object. This allows you to monitor the progress of the task.

1
waitForDone(taskId: string, options?: {
2
sleepInterval?: number;
3
callback?: (task: TwelvelabsApi.TasksRetrieveResponse) => void | Promise<void>;
4
}, requestOptions?: Tasks.RequestOptions): Promise<TwelvelabsApi.TasksRetrieveResponse>;

Parameters:

Return value: A Promise that resolves to a TasksRetrieveResponse representing the completed task. See the Retrieve a video indexing task section above for complete property details.

List video indexing tasks

Description: This method returns a paginated list of the video indexing tasks in your account based on the provided parameters. By default, the platform returns your video indexing tasks sorted by creation date, with the newest at the top of the list.

Function signature and example:

1
list(request?: TwelvelabsApi.TasksListRequest, requestOptions?: Tasks.RequestOptions): Promise<core.Page<TwelvelabsApi.VideoIndexingTask>>;

Parameters:

The TasksListRequest interface defines the parameters for listing video indexing tasks:

Return value: Returns a Promise that resolves to a Page<VideoIndexingTask> object that implements AsyncIterable, allowing you to iterate through the results.

The VideoIndexingTask interface contains the following properties:

The VideoIndexingTaskSystemMetadata interface contains the following properties:

API Reference: List video indexing tasks.

Delete a video indexing task

Description: This method deletes an existing video indexing task. This action cannot be undone. You can only delete video indexing tasks for which the status is ready or failed. If the status of your video indexing task is ready, you must first delete the video vector associated with your video indexing task.

Function signature and example:

1
delete(taskId: string, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<void>;

Parameters:

Return value: Returns a Promise that resolves to void. This method doesn’t return any data upon successful completion.

API Reference: Delete a video indexing task.

Import videos

Description: An import represents the process of uploading and indexing all videos from the specified integration. This method initiates an asynchronous import and returns two lists: videos that will be imported, and videos that will not be imported, typically due to unmet prerequisites. The actual uploading and indexing of videos occur asynchronously after you invoke this method.

Function signature and example:

1
create(integrationId: string, request: TwelvelabsApi.tasks.TransfersCreateRequest, requestOptions?: Transfers.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.tasks.TransfersCreateResponse>;

Parameters:

The TransfersCreateRequest interface defines the parameters for importing videos:

Return value: Returns a Promise that resolves to a TransfersCreateResponse object containing two lists: videos that will be imported, and videos that will not be imported.

The TransfersCreateResponse interface contains the following properties:

The TransfersCreateResponseVideosItem interface contains the following properties:

The TransfersCreateResponseFailedFilesItem interface contains the following properties:

API Reference: Import videos.

Related guide: Cloud-to-cloud integrations.

Retrieve import status

Description: This method retrieves the current status for each video from a specified integration and index, returning lists of videos grouped by their import status.

Function signature and example:

1
getStatus(integrationId: string, request: TwelvelabsApi.tasks.TransfersGetStatusRequest, requestOptions?: Transfers.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.tasks.TransfersGetStatusResponse>;

Parameters:

The TransfersGetStatusRequest interface defines the parameters for retrieving import status:

Return value: Returns a Promise that resolves to a TransfersGetStatusResponse object containing lists of videos grouped by status.

The TransfersGetStatusResponse interface contains the following properties:

The VideoItem interface contains the following properties:

The VideoItemFailed interface contains the following properties:

API Reference: Retrieve import status.

Related guide: Cloud-to-cloud integrations.

Retrieve import logs

Description: This method returns a chronological list of import operations for the specified integration. The list is sorted by creation date, with the oldest imports first. Each item in the list contains the number of videos in each status and detailed error information for failed uploads, including filenames and error messages. Use this method to track import progress and troubleshoot potential issues across multiple operations.

Function signature and example:

1
getLogs(integrationId: string, requestOptions?: Transfers.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.tasks.TransfersGetLogsResponse>;

Parameters:

Return value: Returns a Promise that resolves to a TransfersGetLogsResponse object containing a chronological list of import operations for the specified integration.

The TransfersGetLogsResponse interface contains the following properties:

The ImportLog interface contains the following properties:

The ImportLogVideoStatus interface contains the following properties:

The ImportLogFailedFilesItem interface contains the following properties:

API Reference: Retrieve import logs.

Related guide: Cloud-to-cloud integrations.

Error codes

This section lists the most common error messages you may encounter while uploading videos.

• video_resolution_too_low
  • The resolution of the video is too low. Please upload a video with resolution between 360x360 and 3840x2160. Current resolution is {current_resolution}.
• video_resolution_too_high
  • The resolution of the video is too high. Please upload a video with resolution between 360x360 and 3840x2160. Current resolution is {current_resolution}.
• video_resolution_invalid_aspect_ratio
  • The aspect ratio of the video is invalid. Please upload a video with aspect ratio between 1:1 and 2.4:1. Current resolution is {current_resolution}.
• video_duration_too_short
  • Video is too short. Please use video with duration between 10 seconds and 2 hours(7200 seconds). Current duration is {current_duration} seconds.
• video_duration_too_long
  • Video is too long. Please use video with duration between 10 seconds and 2 hours(7200 seconds). Current duration is {current_duration} seconds.
• video_file_broken
  • Cannot read video file. Please check the video file is valid and try again.
• task_cannot_be_deleted
  • (Returns raw error message)
• usage_limit_exceeded
  • Not enough free credit. Please register a payment method or contact sales@twelvelabs.io.
• video_filesize_too_large
  • The video is too large. Please use a video with a size less than {maximum_size}. The current size is {current_file_size}.