API ReferenceUpload contentDirect uploads

Create an asset

This method creates an asset by uploading a file to the platform. Assets are files (such as images, audio, or video) that you can use in downstream workflows, including indexing, analyzing video content, and creating entities. **Supported content**: Video, audio, and images. **Upload methods**: - **Local file**: Set the `method` parameter to `direct` and use the `file` parameter to specify the file. - **Publicly accessible URL**: Set the `method` parameter to `url` and use the `url` parameter to specify the URL of your file. **File size**: 200MB maximum for local file uploads, 4GB maximum for URL uploads. **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) - **Entity search**: [Marengo image requirements](/v1.3/docs/concepts/models/marengo#image-file-requirements) - **Create embeddings**: [Marengo requirements](/v1.3/docs/concepts/models/marengo#input-requirements)

Authentication

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

Request

This endpoint expects a multipart form containing an optional file.
methodenumRequired

Specifies the upload method for the asset. Use direct to upload a local file or url for a publicly accessible URL.

Allowed values:
filefileOptional
Specify this parameter to upload a file from your local file system. This parameter is required when `method` is set to `direct`. <Note title="Note"> Direct uploads are limited to 200MB. For files larger than 200MB, use the [Multipart Upload API](/assets/upload). </Note>
urlstringOptional
Specify this parameter to upload a file from a publicly accessible URL. This parameter is required when `method` is set to `url`. <Note title="Note"> URL uploads are limited to 4GB. </Note>
filenamestringOptional1-255 characters
The optional filename of the asset. If not provided, the platform will determine the filename from the file or URL.

Response

The asset has been successfully created.
_idstring or null
The unique identifier of the asset.
methodenum or null
Indicates how you uploaded the asset. **Values**: - `direct`: Uploaded from your local file system - `url`: Uploaded from a publicly accessible URL
Allowed values:
statusenum or null
Indicates the current state of the asset. **Values**: - `waiting`: The platform is preparing to process the upload - `processing`: The platform is processing the uploaded file - `ready`: The asset is ready to use
Allowed values:
filenamestring or null
The name of the file used to create the asset.
file_typestring or null
The MIME type of the asset file.
urlstring or null
The URL where you can access the asset file. Use this URL to preview or download the asset. <Note title="Note"> This URL expires after the time specified in the `url_expires_at` field. After expiration, you must retrieve the asset again to obtain a new URL. </Note>
url_expires_atstring or nullformat: "date-time"

The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the URL expires. After this time, the URL in the url field becomes invalid. Retrieve the asset again to obtain a new URL.

created_atstring or nullformat: "date-time"

The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.

Errors