Node.js SDKAssetsUpload files

Direct uploads

The Assets class provides methods to upload your media and documents to the platform. This method creates an asset that you can use in different workflows.

Workflow

1

Upload your file using the assets.create method. You receive the identifier of the asset in the response.

2

Asset processing is asynchronous. Poll the assets.retrieve method until the status field is ready before proceeding.

3

What you do next depends on your use case:

  • For creating embeddings (videos, audio, images): Use the identifier of the asset with the Embed API v2.
  • For entity search (images): Use the identifier of the asset to create entities.
  • For search and analysis (videos): Index your asset using the identifier of the asset.

Methods

Create an asset

Description: 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, typically within a few seconds to a few minutes. Poll the assets.retrieve method until the status field is ready before you use the asset. 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:

Note

This method is rate-limited. For details, see the Rate limits page.

Function signature and example:

1create(
2    request: TwelvelabsApi.AssetsCreateRequest,
3    requestOptions?: Assets.RequestOptions
4): core.HttpResponsePromise<TwelvelabsApi.Asset>

Parameters

NameTypeRequiredDescription
requestTwelvelabsApi.AssetsCreateRequestYesParameters for creating an asset.
requestOptionsAssets.RequestOptionsNoRequest-specific configuration.

The TwelvelabsApi.AssetsCreateRequest interface has the following properties:

NameTypeRequiredDescription
methodTwelvelabsApi.AssetsCreateRequestMethodYesSpecifies the upload method for the asset. Use direct to upload a local file or url for a publicly accessible URL.
fileFile | fs.ReadStream | Blob | undefinedNoThe local file to upload. 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.
urlstringNoThe publicly accessible URL of a media file or document to upload. 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.
filenamestringNoThe 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.
enableHlsbooleanNoWhen set to true, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only. The platform ignores this flag for other asset types. Default: false.
enableThumbnailbooleanNoWhen set to true, the platform generates thumbnail images from the uploaded content. For PDF files, the representative thumbnail uses the first page. Text and Markdown files do not produce thumbnails; the platform ignores this flag for them. Default: false.
userMetadatastringNoMetadata 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.

Return value

Returns an HttpResponsePromise that resolves to a TwelvelabsApi.Asset object representing the created asset.

The TwelvelabsApi.Asset interface contains the following properties:

NameTypeDescription
idstringThe unique identifier of the asset.
methodTwelvelabsApi.AssetMethodIndicates 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).
statusTwelvelabsApi.AssetStatusIndicates the current processing status of the asset. Values: processing (the asset is not yet usable; the upload is still in progress, or the platform is validating the file), ready (the platform validated the asset successfully and it is ready to use), failed (the platform could not process the file; the error field describes the reason).
filenamestringThe name of the file used to create the asset.
fileTypestringThe MIME type of the asset file. For documents, this is application/pdf, text/plain, or text/markdown.
createdAtDateThe date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.
userMetadataTwelvelabsApi.UserMetadataUser-defined metadata for this asset. This field is absent when no metadata has been set.
sourceTwelvelabsApi.AssetSourceDescribes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the /assets endpoint.

API Reference

Create an asset