Use multipart uploads for local video files up to 4 GB. This method divides the file into smaller chunks for reliable uploads, especially when you need parallel chunk uploads or want to resume an interrupted transfer.

Multipart uploads create assets that you can use in different workflows.

High-level upload methods

The MultipartUploadClientWrapper class provides convenience methods that simplify multipart uploads. Use these methods for most upload scenarios.

For a complete example that demonstrates progress tracking, error handling, and batch uploads, see the multipart_uploads.py example in the SDK repository.

Upload a file

Description: Upload a local video file using multipart upload with automatic chunking, parallel uploads, progress tracking, and retry logic.

Function signature and example:

1
def upload_file(
2
    self,
3
    file_path: typing.Union[str, Path],
4
    *,
5
    filename: typing.Optional[str] = None,
6
    file_type: CreateAssetUploadRequestType = "video",
7
    batch_size: int = 10,
8
    max_workers: int = 5,
9
    progress_callback: typing.Optional[typing.Callable[[UploadProgress], None]] = None,
10
    max_retries: int = 3,
11
    retry_delay: float = 1.0,
12
    request_options: typing.Optional[RequestOptions] = None,
13
) -> UploadResult

Parameters

Return value

Returns an UploadResult object.

The UploadResult class contains the following properties:

The UploadProgress class (used in progress_callback) contains the following properties:

Monitor upload completion

Description: Monitor a multipart upload by checking its status at regular intervals.

Function signature and example:

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

Parameters

Return value

Returns an UploadStatus object.

The UploadStatus class contains the following properties:

Low-level API methods

The MultipartUploadClient class provides methods to manage multipart upload sessions. Use these methods when you need fine-grained control over the upload process.

Workflow

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 for a local video file.

Supported content: Video

Upload limits: Local video files larger than 200 MB, up to 4 GB.

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
    type: CreateAssetUploadRequestType,
6
    total_size: int,
7
    enable_hls: typing.Optional[bool] = OMIT,
8
    enable_thumbnail: typing.Optional[bool] = OMIT,
9
    request_options: typing.Optional[RequestOptions] = None
10
) -> 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:

The PresignedUrlChunk class contains the following properties:

API Reference

Request presigned URLs for the remaining chunks