assets

Create an asset

Changed on

This method creates an asset by uploading a file to the platform. Assets are reusable files that you can use in different workflows.

The platform processes uploads asynchronously. This method returns immediately with the asset in the processing status, which then transitions to the ready status on success or to the failed status when the file is invalid, corrupt, or unreadable. Poll the Retrieve an asset 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.
  • PDF, text, and Markdown files.

Filename extension matching is case-insensitive; for example, notes.MD and notes.md are treated the same. The platform rejects unsupported formats. For documents, it also rejects files whose extensions don't match the detected content.

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
  • Documents, local files: Up to 200 MB
  • Documents, public URLs: Up to 512 MB

Asset creation does not enforce a maximum duration for video and audio files. Each model applies its own file size and duration limits. For details, see the requirements below.

Additional requirements depend on your workflow:

  • Search: Marengo requirements
  • Video analysis: Pegasus requirements
  • Entity search: Marengo image requirements
  • Create embeddings: Marengo requirements
<Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>
post/assets

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/assets
  • Auth: API key in header x-api-key

Request body multipart/form-data

method'direct' | 'url' required

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

filestring binary

Specify this parameter to upload a file from your local file system. This parameter is required when method is set to direct.

Local video, audio, and documents support up to 200 MB. Images support up to 32 MB.

urlstring

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. Document URLs support up to 512 MB.

The parameter also accepts the URL of an HLS manifest (.m3u8) in VOD format. Live video streams are rejected with a 400 error. If the duration cannot be determined from the media, the platform calculates it from the manifest.

filenamestring

The filename of the asset. If you provide a filename, the platform preserves it. If you omit it, the platform determines one from the file or URL.

enable_hlsboolean

The platform generates an HLS playlist and segments for streaming. Set to false to disable HLS generation. Applicable to video and audio assets only. The platform ignores this flag for other asset types.

Default: true.

enable_thumbnailboolean

The platform generates thumbnail images from the uploaded content. Set to false to disable thumbnail generation.

For PDF files, the platform generates a representative thumbnail from the first page. Text and Markdown files do not produce thumbnails; the platform ignores this flag for them.

Default: true.

user_metadatastring

Metadata that helps you categorize your assets. You can specify a list of keys and values. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991), and any identifier you want preserved verbatim, as a string. Send this value as a JSON-encoded string.

Response

The asset has been successfully created.

_idstring

The unique identifier of the asset.

method'direct' | 'url' | 'multipart' | 'connector'

Indicates how the asset was uploaded or imported.

Values:

  • direct: Uploaded from your local file system
  • url: Uploaded from a publicly accessible URL
  • multipart: Uploaded using the multipart upload flow
  • connector: Imported through a data connector
status'failed' | 'processing' | 'ready'

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 different 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. For documents, this is application/pdf, text/plain, or text/markdown.

created_atstring date-time

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

user_metadataUserMetadata

Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings. Each value is a string, a number, a boolean, or an array of strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991), and any identifier you want preserved verbatim, as a string.

Example:

"user_metadata": {
  "category": "recentlyAdded",
  "batchNumber": 5,
  "rating": 9.3,
  "needsReview": true,
  "hashtags": ["summer", "vlog"]
}

Changes