Assets and entitiesUpload contentDirect uploads

Create an asset

This method creates an asset by uploading a file to the platform. Assets are media files that you can use in downstream workflows, including indexing, analyzing video content, and creating entities. The platform processes uploads asynchronously. This method returns immediately with the asset in the `processing` status, which then transitions to `ready` on success or to `failed` when the file is invalid or corrupt, typically within a few seconds to a few minutes. Poll the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) endpoint until the status of the asset is `ready` before you use it. This applies to every upload, including small files. **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. **Upload limits**: - **Video and audio, local files**: Up to 200 MB - **Video and audio, public URLs**: Up to 4 GB - **Images**: Up to 32 MB Asset creation does not enforce a maximum duration. Each model applies its own file size and duration limits when you index or analyze the asset. For details, see the requirements below. **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) <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>

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-keys" target="_blank">API Keys</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.

Local video and audio files support up to 200 MB. Image files support up to 32 MB.

urlstringOptional

Specify this parameter to upload a file from a publicly accessible URL. This parameter is required when method is set to url.

Public video and audio URLs support up to 4 GB. Image URLs support up to 32 MB.

filenamestringOptional1-255 characters
The optional filename of the asset. If not provided, the platform will determine the filename from the file or URL.
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_metadatastringOptional

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. Send this value as a JSON-encoded string.

Response

The asset has been successfully created.
_idstring
The unique identifier of the asset.
methodenum

Indicates how you uploaded the asset.

Values:

  • direct: Uploaded from your local file system
  • url: Uploaded from a publicly accessible URL
  • multipart: Uploaded using the multipart upload flow
statusenum

Indicates the current processing status of the asset.

A newly uploaded asset starts in the processing status and transitions asynchronously to ready on success or to failed on error, typically within a few seconds to a few minutes. Poll the Retrieve an asset endpoint until the status is ready before you use the asset in downstream workflows.

Values:

  • processing: The asset is not yet usable. This can mean the upload is still in progress (for example, the platform is still fetching the file from a URL, or a multipart upload has not completed), or the upload has finished and the platform is validating the file. The technical_metadata field is omitted from the response.
  • ready: The platform validated the asset successfully, and the asset is ready to use.
  • failed: The platform could not process the file. The error field describes the reason, and the technical_metadata field may be partially populated.
filenamestring
The name of the file used to create the asset.
file_typestring
The MIME type of the asset file.
created_atstringformat: "date-time"

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

user_metadatamap from strings to any

User-defined metadata for this asset. This field is absent when no metadata has been set.

sourceobject

Describes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the /assets endpoint.

Errors

400
Bad Request Error