A video indexing task represents a request to upload and index a video. The TaskClientWrapper 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
def create(
2
    self,
3
    *,
4
    index_id: str,
5
    video_file: typing.Optional[core.File] = OMIT,
6
    video_url: typing.Optional[str] = OMIT,
7
    enable_video_stream: typing.Optional[bool] = OMIT,
8
    request_options: typing.Optional[RequestOptions] = None,
9
) -> TasksCreateResponse:

Parameters:

Return value: Returns 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
def retrieve(
2
    self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None
3
) -> TasksRetrieveResponse

Parameters:

Return value: Returns a TasksRetrieveResponse object representing the retrieved video indexing task.

The TasksRetrieveResponse class extends VideoIndexingTask and contains the following properties:

The VideoIndexingTaskSystemMetadata class contains the following properties:

The HlsObject class 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.

Function signature and example:

1
def wait_for_done(
2
    self,
3
    task_id: str,
4
    *,
5
    sleep_interval: float = 5.0,
6
    callback: typing.Optional[
7
        typing.Callable[[TasksRetrieveResponse], None]
8
    ] = None,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> TasksRetrieveResponse

Parameters:

Return value: Returns a TasksRetrieveResponse object 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. 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
def list(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    sort_by: typing.Optional[str] = None,
7
    sort_option: typing.Optional[str] = None,
8
    index_id: typing.Optional[str] = None,
9
    status: typing.Optional[
10
        typing.Union[TasksListRequestStatusItem, typing.Sequence[TasksListRequestStatusItem]]
11
    ] = None,
12
    filename: typing.Optional[str] = None,
13
    duration: typing.Optional[float] = None,
14
    width: typing.Optional[int] = None,
15
    height: typing.Optional[int] = None,
16
    created_at: typing.Optional[str] = None,
17
    updated_at: typing.Optional[str] = None,
18
    request_options: typing.Optional[RequestOptions] = None,
19
) -> SyncPager[VideoIndexingTask]

Parameters:

Return value: Returns a SyncPager[VideoIndexingTask] object that allows you to iterate through the paginated list of video indexing tasks.

The VideoIndexingTask class contains the following properties:

The VideoIndexingTaskSystemMetadata class 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
def delete(self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None

Parameters:

Return value: None. 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
def create(
2
    self,
3
    integration_id: str,
4
    *,
5
    index_id: str,
6
    incremental_import: typing.Optional[bool] = OMIT,
7
    retry_failed: typing.Optional[bool] = OMIT,
8
    user_metadata: typing.Optional[typing.Dict[str, typing.Optional[typing.Any]]] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None,
10
) -> TransfersCreateResponse

Parameters:

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

The TransfersCreateResponse class contains the following properties:

The TransfersCreateResponseFailedFilesItem class contains the following properties:

The TransfersCreateResponseVideosItem class 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. Use this method to track import progress and troubleshoot potential issues across multiple operations.

Function signature and example:

1
def get_status(
2
    self,
3
    integration_id: str,
4
    *,
5
    index_id: str,
6
    request_options: typing.Optional[RequestOptions] = None
7
) -> TransfersGetStatusResponse

Parameters:

Return value: Returns a TransfersGetStatusResponse object containing lists of videos grouped by status.

The TransfersGetStatusResponse class contains the following properties:

The VideoItem class contains the following properties:

The VideoItemFailed class 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, sorted by creation date with the oldest imports first. Each log entry includes the number of videos in each status and detailed error information for failed uploads.

Function signature and example:

1
def get_logs(
2
    self,
3
    integration_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None
6
) -> TransfersGetLogsResponse

Parameters:

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

The TransfersGetLogsResponse class contains the following properties:

The ImportLog class contains the following properties:

The ImportLogVideoStatus class contains the following properties:

The ImportLogFailedFilesItem class 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}.