For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
This method creates a multipart upload session for a local video file.
**Supported content**: Video
**Upload limits**: Local video files up to 4 GB.
**Additional requirements** depend on your workflow:
- **Search**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#video-file-requirements)
- **Video analysis**: [Pegasus requirements](/v1.3/docs/concepts/models/pegasus#input-requirements)
- **Create embeddings**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#input-requirements)
This method creates a multipart upload session for a local video file.
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
This endpoint expects an object.
filenamestringRequired1-255 characters
The original file name of the asset.
typeenumRequired
The type of asset you want to upload.
Allowed values:
total_sizeintegerRequired1-4294967296
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
enable_hlsbooleanOptionalDefaults to false
When set to true, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only.
Default: false.
enable_thumbnailbooleanOptionalDefaults to false
When set to true, the platform generates thumbnail images from the uploaded content.
Default: false.
user_metadatamap from strings to anyOptional
Metadata that helps you categorize your assets. You can specify a list of keys and values. Keys must be of type string, and values can be of the following types: string, integer, float, or boolean.
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_urlslist of objects
An array containing the initial set of presigned URLs for uploading chunks. Each URL corresponds to a specific chunk.
Note the following about the presigned URLs:
URLs expire after one hour.
Depending on the size of the file, the initial set may not include URLs for all chunks. If you need more URLs, you can request additional ones using the POST method of the /assets/multipart-uploads/{upload_id}/presigned-urls endpoint.
upload_headersmap from strings to strings
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_atstringformat: "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.
