Sign in
multipartUpload

Create a multipart upload session

This method creates a multipart upload session for a local file.

Supported content: Video, audio, and images.

Upload limits:

  • Video and audio: Up to 10 GB
  • Images: Up to 32 MB

Additional requirements depend on your workflow:

  • Search: Marengo requirements
  • Video analysis: Pegasus requirements
  • Entity search: Marengo image requirements
  • Create embeddings: Marengo requirements
post/assets/multipart-uploads

Headers

x-api-keystring required

Your API key.

<Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request body

filenamestring required

The original file name of the asset.

type'video' | 'audio' | 'image' required

The type of asset you want to upload.

total_sizeinteger required

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

Upload limits:

  • Video and audio: Up to 10 GB
  • Images: Up to 32 MB
enable_hlsboolean

When set to true, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only.

Default: false.

enable_thumbnailboolean

When set to true, the platform generates thumbnail images from the uploaded content.

Default: false.

user_metadataUserMetadata

Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of string, integer, float, or boolean.

Example:

"user_metadata": {
  "category": "recentlyAdded",
  "batchNumber": 5,
  "rating": 9.3,
  "needsReview": true
}
<Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>

Response

The multipart upload session has been successfully created.

upload_idstring

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.

asset_idstring

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.

upload_headersobject
chunk_sizeinteger

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.

total_chunksinteger

The total number of chunks into which your file must be split. Calculated as: ceiling(total_size / chunk_size).

expires_atstring date-time

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.

Changes

Changed in 3 of the 8 revisions of this API.162

  • fd9d80e384a813See the full diff
    • ▲

      the filename request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ●

      the filename request property's maxLength was set to 255

      request-property-max-length-set

    • ●

      the total_size request property's max was set to 10737418240.00

      request-property-max-set

    • ●

      the total_size request property's min was set to 1.00

      request-property-min-set

  • 5dbd6e8473c93See the full diff
    • ●

      removed the optional property docs_url from the response with the 400 status

      response-optional-property-removed

    • ●

      removed the optional property docs_url from the response with the 403 status

      response-optional-property-removed

    • ●

      removed the optional property docs_url from the response with the 500 status

      response-optional-property-removed

  • c0926990c6622See the full diff
    • ○

      added the new audio enum value to the request property type

      request-property-enum-value-added

    • ○

      added the new image enum value to the request property type

      request-property-enum-value-added

    This revision also has 35 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog