The MultipartUploadClient class provides methods to manage multipart upload sessions.

Utilize multipart uploads to upload large files by dividing them into smaller chunks. This approach enables reliable uploads of large files, particularly when processing chunks in parallel or resuming interrupted transfers. TwelveLabs recommends using this method for files larger than 200 MB, with a maximum size limit of 4 GB.

This method creates an asset that you can use in different workflows.

Workflow

Methods

List incomplete uploads

Description: This method returns a list of all incomplete multipart upload sessions in your account.

Function signature and example:

1
def list_incomplete_uploads(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> SyncPager[IncompleteUploadSummary]

Parameters:

Return value: Returns a SyncPager[IncompleteUploadSummary] object that allows you to iterate through the paginated results.

The SyncPager[T] class contains the following properties and methods:

The IncompleteUploadSummary class contains the following properties:

API Reference: List incomplete uploads

Create a multipart upload session

Description: This method creates a multipart upload session.

Supported content: Video and audio

File size: 4GB maximum.

Additional requirements depend on your workflow:

• Search: Marengo requirements
• Video analysis: Pegasus requirements
• Create embeddings: Marengo requirements

Function signature and example:

1
def create(
2
    self,
3
    *,
4
    filename: str,
5
    total_size: int,
6
    request_options: typing.Optional[RequestOptions] = None
7
) -> CreateAssetUploadResponse

Parameters:

Return value: Returns a CreateAssetUploadResponse object containing details about the upload session.

The CreateAssetUploadResponse class contains the following properties:

The PresignedUrlChunk class contains the following properties:

API Reference: Create a multipart upload session

Retrieve the status of an upload session

Description: This method retrieves information about an upload session, including its current status, chunk-level progress, and completion state.

Use this method to:

• Verify upload completion (status = completed)
• Identify any failed chunks that require a retry
• Monitor the upload progress by comparing uploaded_size with total_size
• Determine if the session has expired
• Retrieve the status information for each chunk

You must call this method after reporting chunk completion to confirm the upload has transitioned to the completed status before using the asset.

Function signature and example:

1
def get_status(
2
    self,
3
    upload_id: str,
4
    *,
5
    page: typing.Optional[int] = None,
6
    page_limit: typing.Optional[int] = None,
7
    request_options: typing.Optional[RequestOptions] = None,
8
) -> SyncPager[ChunkInfo]

Parameters:

Return value: Returns a SyncPager[ChunkInfo] object that allows you to iterate through the paginated chunk status information.

The SyncPager[T] class contains the following properties and methods:

The ChunkInfo class contains the following properties:

API Reference: Retrieve the status of an upload session

Report uploaded chunks

Description: This method reports successfully uploaded chunks to the platform. The platform finalizes the upload after you report all chunks.

For optimal performance, report chunks in batches and in any order.

Function signature and example:

1
def report_chunk_batch(
2
    self,
3
    upload_id: str,
4
    *,
5
    completed_chunks: typing.Sequence[CompletedChunk],
6
    request_options: typing.Optional[RequestOptions] = None,
7
) -> ReportChunkBatchResponse

Parameters:

The CompletedChunk class contains the following properties:

Return value: Returns a ReportChunkBatchResponse object containing information about the reported chunks.

The ReportChunkBatchResponse class contains the following properties:

API Reference: Report uploaded chunks

Request presigned URLs for the remaining chunks

Description: This method generates new presigned URLs for specific chunks that require uploading. Use this method in the following situations:

• Your initial URLs have expired (URLs expire after one hour).
• The initial set of presigned URLs does not include URLs for all chunks.
• You need to retry failed chunk uploads with new URLs.

To specify which chunks need URLs, use the start and count parameters. For example, to generate URLs for chunks 21 to 30, use start=21 and count=10.

The response provides new URLs, each with a fresh expiration time of one hour.

Function signature and example:

1
def get_additional_presigned_urls(
2
    self,
3
    upload_id: str,
4
    *,
5
    start: int,
6
    count: int,
7
    request_options: typing.Optional[RequestOptions] = None
8
) -> RequestAdditionalPresignedUrLsResponse

Parameters:

Return value: Returns a RequestAdditionalPresignedUrLsResponse object containing the new presigned URLs.

The RequestAdditionalPresignedUrLsResponse class contains the following properties:

API Reference: Request presigned URLs for the remaining chunks