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.

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

High-level upload methods

The MultipartUploadWrapper 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.ts example in the SDK repository.

Upload a file

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

Function signature and example:

1 uploadFile(
2     filePath: string,
3     options?: UploadFileOptions
4 ): Promise<UploadResult>

Parameters:

Name	Type	Required	Description
`filePath`	`string`	Yes	The path to the file to upload.
`options`	`UploadFileOptions`	No	Upload configuration options.

The UploadFileOptions interface has the following properties:

Name	Type	Required	Description
`filename`	`string`	No	The filename of the asset. Defaults to the file basename.
`fileType`	`TwelvelabsApi.CreateAssetUploadRequestType`	No	The MIME type of the asset file. Default: `"video"`.
`batchSize`	`number`	No	The number of chunks to report in each batch. Default: `10`.
`maxWorkers`	`number`	No	The maximum concurrent upload workers. Default: `5`.
`progressCallback`	`(progress: UploadProgress) => void`	No	The callback function for progress updates.
`maxRetries`	`number`	No	The maximum retry attempts for failed chunks. Default: `3`.
`retryDelay`	`number`	No	The delay between retries in seconds. Default: `1.0`. Uses exponential backoff.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an UploadResult object.

The UploadResult interface contains the following properties:

Name	Type	Description
`assetId`	`string`	The unique identifier of the uploaded asset.
`assetUrl`	`string`	The URL to access the uploaded asset.

The UploadProgress interface (used in progressCallback) contains the following properties:

Name	Type	Description
`totalChunks`	`number`	The Total number of chunks.
`completedChunks`	`number`	The number of completed chunks.
`percentage`	`number`	The upload percentage (0-100).
`status`	`string`	The current upload status.

Monitor upload completion

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

Function signature and example:

1 waitForUploadCompletion(
2     uploadId: string,
3     options?: WaitForCompletionOptions
4 ): Promise<UploadStatus>

Parameters:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`options`	`WaitForCompletionOptions`	No	Wait configuration options.

The WaitForCompletionOptions interface has the following properties:

Name	Type	Required	Description
`sleepInterval`	`number`	No	The wait time between status checks in seconds. Default: `5.0`.
`maxWaitTime`	`number`	No	The maximum wait time in seconds before timeout. Default: `undefined` (no timeout).
`callback`	`(status: UploadStatus) => void`	No	The function called after each status check.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an UploadStatus object.

The UploadStatus interface contains the following properties:

Name	Type	Description
`status`	`string`	The upload status (“completed” or “in_progress”).
`completedChunks`	`number`	The number of completed chunks.
`totalChunks`	`number`	The total number of chunks.

Low-level API methods

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

Workflow

Determine the total size of your file in bytes. You’ll need this value when creating the upload session.

Create an upload session: Call the multipartUpload.create` method, providing details about your file, including its size. The response contains, among other information, the unique identifier of the asset, a list of upload URLs, and the size of each chunk in bytes.

Split your file: Use the chunk size from the response to divide your file into chunks of the specified size.

Upload chunks: Transfer each chunk to its designated presigned URL. You can upload the chunks in parallel for improved performance. Save the ETag from each upload response for progress reporting.

(Optional) Request additional URLs: Call the multipartUpload.getAdditionalPresignedUrls method if you need URLs for remaining chunks or if existing URLs expire.

Report progress: Submit completed chunks via the multipartUpload.getAdditionalPresignedUrls method in batches as chunks finish uploading. Use the ETag from each chunk upload as proof of successful transfer.

Confirm completion: The upload is complete when the multipartUpload.getStatus method returns status: 'completed'. Use the asset ID from step 1 to perform additional operations on your uploaded video.

What you do next depends on your use case:

For creating embeddings (videos, audio, images): Use the asset ID with the Embed API v2.
For search and analysis (videos): Index an asset using the asset ID.

Methods

List incomplete uploads

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

Function signature and example:

1 listIncompleteUploads(
2     request?: TwelvelabsApi.MultipartUploadListIncompleteUploadsRequest,
3     requestOptions?: MultipartUpload.RequestOptions
4 ): Promise<core.Page<TwelvelabsApi.IncompleteUploadSummary>>

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.MultipartUploadListIncompleteUploadsRequest`	Yes	Parameters for listing incomplete uploads.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.MultipartUploadListIncompleteUploadsRequest interface has the following properties:

Name	Type	Required	Description
`page`	`number`	No	A number that identifies the page to retrieve. Default: `1`.
`pageLimit`	`number`	No	The number of items to return on each page. Default: `10`. Max: `50`.

Return value: Returns a Promise that resolves to a Page<IncompleteUploadSummary> object that allows you to iterate through the paginated results.

The Page<T> interface contains the following properties and methods:

Name	Type	Description
`data`	`T[]`	An array containing the current page of items.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`getNextPage()`	`Promise<Page<T>>`	Retrieves the next page and returns the updated `Page` object.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	Allows iteration through all items across all pages using `for await` loops.

The TwelvelabsApi.IncompleteUploadSummary interface contains the following properties:

Name	Type	Description
`uploadId`	`string`	The unique identifier of your upload session.
`status`	`TwelvelabsApi.MultipartUploadStatusType`	The current status of the upload session. Values: “active”, “completed”, “failed”, “expired”.
`totalSize`	`number`	Total size of the file in bytes.
`chunkSize`	`number`	The size of each chunk in bytes.
`totalChunks`	`number`	The total number of chunks in this upload session.
`createdAt`	`Date`	The date and time when the upload session was created.
`expiresAt`	`Date`	The date and time when the upload session expires.

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 create(
2     request: TwelvelabsApi.CreateAssetUploadRequest,
3     requestOptions?: MultipartUpload.RequestOptions
4 ): core.HttpResponsePromise<TwelvelabsApi.CreateAssetUploadResponse>

Parameters:

Name	Type	Required	Description
`request`	`TwelvelabsApi.CreateAssetUploadRequest`	Yes	Parameters for creating a multipart upload session.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.CreateAssetUploadRequest interface has the following properties:

Name	Type	Required	Description
`filename`	`string`	Yes	The original file name of the asset.
`type`	`TwelvelabsApi.CreateAssetUploadRequestType`	The type of asset you want to upload. Value: “video”.
`totalSize`	`number`	Yes	The total size of the file in bytes. The platform uses this value to: - Calculate the optimal chunk size. - Determine the total number of chunks required - Generate the initial set of presigned URLs

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.CreateAssetUploadResponse object containing the upload session details.

The TwelvelabsApi.CreateAssetUploadResponse interface contains the following properties:

Name	Type	Description
`uploadId`	`string`	The unique identifier of this upload session. Store this value, as you’ll need it for the following subsequent operations: - Reporting completed chunks - Requesting additional presigned URLs - Retrieving the status of this upload session This identifier remains valid for 24 hours from the time of creation.
`assetId`	`string`	The unique identifier for the asset being created. Store this value, as you’ll need it to reference the asset in other API calls. Note that this identifier is reserved immediately, but the asset becomes available for other operations only after the upload is completed successfully.
`uploadUrls`	`TwelvelabsApi.PresignedUrlChunk[]`	The initial set of presigned URLs for uploading chunks. Each URL corresponds to a specific chunk. NOTES: - URLs expire after one hour. - Depending on the size of the file, this initial set may not include URLs for all chunks. You can request more using the `getAdditionalPresignedUrls` method.
`uploadHeaders`	`Record<string, string>`	Headers to include when uploading chunks to the presigned URLs.
`chunkSize`	`number`	The size in bytes for each chunk, except for the last chunk, which may be smaller. Use this value to divide your file into chunks of this exact size.
`totalChunks`	`number`	The total number of chunks into which your file must be split. Calculated as: ceiling(`totalSize` / `chunkSize`).
`expiresAt`	`Date`	A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the upload URL will expire. Upload URLs expire 24 hours from their creation. After expiration, you cannot resume the upload, and you must create a new upload session.

The TwelvelabsApi.PresignedUrlChunk interface contains the following properties:

Name	Type	Description
`chunkIndex`	`number`	The index of this chunk.
`url`	`string`	The presigned URL for uploading this chunk. Each URL can only be used once and expires after one hour.
`expiresAt`	`Date`	The date and time when the presigned URL expires.

API Reference: Create a multipart upload session

Retrieve the status of an upload session

Description: This method provides 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 getStatus(
2     uploadId: string,
3     request?: TwelvelabsApi.MultipartUploadGetStatusRequest,
4     requestOptions?: MultipartUpload.RequestOptions
5 ): Promise<core.Page<TwelvelabsApi.ChunkInfo>>

Parameters:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`request`	`TwelvelabsApi.MultipartUploadGetStatusRequest`	Parameters for retrieving the status of your upload session.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.MultipartUploadGetStatusRequest interface has the following properties:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`page`	`number`	No	A number that identifies the page to retrieve. Default: `1`.
`pageLimit`	`number`	No	The number of items to return on each page. Default: `10`. Max: `50`.

Return value: Returns a Promise that resolves to a Page<TwelvelabsApi.ChunkInfo> object that allows you to iterate through the paginated chunk status information.

The Page<T> interface contains the following properties and methods:

Name	Type	Description
`data`	`T[]`	An array containing the current page of items.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`getNextPage()`	`Promise<Page<T>>`	Retrieves the next page and returns the updated `Page` object.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	Allows iteration through all items across all pages using `for await` loops.

The ChunkInfo interface contains the following properties:

Name	Type	Description
`index`	`number`	The index of the chunk. The platform uses 1-based indexing, and this value matches the value of the `chunkIndex` field in the list of upload URLs.
`status`	`TwelvelabsApi.ChunkInfoStatus`	The current status of this chunk. Values: - `completed`: Successfully uploaded and reported. - `pending`: Not yet reported. A chunk may be in this status if it has been uploaded but not yet reported. - `failed`: The upload process failed; you must retry uploading this chunk.
`uploadedAt`	`Date`	The date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when this chunk was successfully reported as uploaded. The value of this field is `null` for pending or failed chunks.
`updatedAt`	`Date`	The date and time when this chunk was last updated.
`error`	`string`	A detailed error message explaining why this chunk failed. The platform returns this field only when the status is failed.

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 reportChunkBatch(
2     uploadId: string,
3     request: TwelvelabsApi.ReportChunkBatchRequest,
4     requestOptions?: MultipartUpload.RequestOptions
5 ): core.HttpResponsePromise<TwelvelabsApi.ReportChunkBatchResponse>

Parameters:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`request`	`TwelvelabsApi.ReportChunkBatchRequest`	Yes	Parameters for reporting uploaded chunks.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.ReportChunkBatchRequest interface has the following properties:

Name	Type	Required	Description
`completedChunks`	`TwelvelabsApi.CompletedChunk[]`	Yes	The list of chunks successfully uploaded that you’re reporting to the platform. Report only after receiving an ETag.

The TwelvelabsApi.CompletedChunk interface contains the following properties:

Name	Type	Description
`chunkIndex`	`number`	The number that identifies which chunk you uploaded. When you received presigned URLs from the platform, each URL was assigned an index number. Use that same number. The chunks are numbered starting from 1.
`proof`	`string`	The ETag value you received after uploading the chunk. When you upload a chunk to a presigned URLs, the response includes an ETag. Use this value and submit it as proof of successful upload.
`proofType`	`TwelvelabsApi.CompletedChunkProofType`	The verification method. Value: `etag`. Default: `etag`.
`chunkSize`	`number`	The number of bytes uploaded for this chunk. For all chunks except the last, this value equals `chunkSize`. For the last chunk, it may be smaller.

Return value: Returns a Promise that resolves to a TwelvelabsApi.ReportChunkBatchResponse object containing information about the reported chunks.

The TwelvelabsApi.ReportChunkBatchResponse interface contains the following properties:

Name	Type	Description
`url`	`string`	The URL for accessing your asset. The platform returns this field only when all chunks are reported and the upload is complete. If absent, continue uploading and reporting the remaining chunks.
`assetId`	`string`	The unique identifier of this asset.
`processedChunks`	`number`	The number of chunks accepted from this specific request. This equals the number of chunks in your `completedChunks` array minus any duplicates.
`duplicateChunks`	`number`	The number of chunks in this request that were already reported. Duplicates are ignored and don’t affect your upload.
`totalCompleted`	`number`	The cumulative count of all unique chunks successfully reported across all requests. When this equals `totalChunks`, the upload is complete.

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 getAdditionalPresignedUrls(
2     uploadId: string,
3     request: TwelvelabsApi.RequestAdditionalPresignedUrLsRequest,
4     requestOptions?: MultipartUpload.RequestOptions
5 ): core.HttpResponsePromise<TwelvelabsApi.RequestAdditionalPresignedUrLsResponse>

Parameters:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`request`	`TwelvelabsApi.RequestAdditionalPresignedUrLsRequest`	Yes	Parameters for requesting presigned URLs for the remaining chunks.
`requestOptions`	`MultipartUpload.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.RequestAdditionalPresignedUrLsRequest interface has the following properties:

Name	Type	Required	Description
`uploadId`	`string`	Yes	The unique identifier of the upload session.
`start`	`number`	Yes	The index of the first chunk number to generate URLs for. Chunks are numbered from 1.
`count`	`number`	Yes	The number of presigned URLs to generate starting from the index. You can request a maximum of 50 URLs in a single API call.

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.RequestAdditionalPresignedUrLsResponse object containing the new presigned URLs.

The TwelvelabsApi.RequestAdditionalPresignedUrLsResponse interface contains the following properties:

Name	Type	Description
`uploadId`	`string`	The unique identifier of the upload session associated with these URLs.
`startIndex`	`number`	The index of the first chunk number in this set of URLs. Matches the start value from your request.
`count`	`number`	The number of new URLs created. Matches the count value from your request.
`uploadUrls`	`TwelvelabsApi.PresignedUrlChunk[]`	An array of additional presigned URLs for uploading chunks.
`generatedAt`	`Date`	The date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when these URLs were created. URLs remain valid for 1 hour from this time.
`expiresAt`	`Date`	The date and time when the upload session expires.

The TwelvelabsApi.PresignedUrlChunk interface contains the following properties:

Name	Type	Description
`chunkIndex`	`number`	The index of this chunk.
`url`	`string`	The presigned URL for uploading this chunk. Each URL can only be used once and expires after 1 hour.
`expiresAt`	`Date`	The date and time when this presigned URL expires.

API Reference: Request presigned URLs for the remaining chunks