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

Workflow

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

Monitor the indexing status using the assets.retrieve method until it’s ready.

What you do next depends on your use case:

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

Methods

Create an asset

Description: 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.

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
Video analysis: Pegasus requirements
Entity search: Marengo image requirements
Create embeddings: Marengo requirements

Function signature and example:

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

Parameters:

Name	Type	Required	Description
`method`	`TwelvelabsApi.AssetsCreateRequestMethod`	Yes	Specifies the upload method for the asset. Use `direct` to upload a local file or `url` for a publicly accessible URL.
`file`	`File \| fs.ReadStream \| Blob \| undefined`	No	The local file to upload. This parameter is required when `method` is set to `direct`.
`url`	`string`	No	The publicly accessible URL of a media file to upload. This parameter is required when `method` is set to `url`. URL uploads have a maximum limit of 4GB.
`filename`	`string`	No	The optional filename of the asset. If not provided, the platform determines the filename from the file or URL.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an Asset object representing the created asset.

The Asset interface contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier of the asset.
`method`	`TwelvelabsApi.AssetMethod`	Indicates how you uploaded the asset. Values: `direct` (uploaded from your local file system), `url` (uploaded from a publicly accessible URL).
`status`	`TwelvelabsApi.AssetStatus`	Indicates the current status 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).
`filename`	`string`	The name of the file used to create the asset.
`fileType`	`string`	The MIME type of the asset file.
`url`	`string`	The URL to access your asset. Use this URL to preview or download the asset. This URL expires after the time specified in the `urlExpiresAt` field. After expiration, you must retrieve the asset again to obtain a new URL.
`urlExpiresAt`	`Date`	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.
`createdAt`	`Date`	The date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the asset was created.

API Reference: Create an asset

List assets

Description: This method returns a list of assets in your account.

The platform returns your assets sorted by creation date, with the newest at the top of the list.

Function signature and example:

1 list(
2     request?: TwelvelabsApi.AssetsListRequest,
3     requestOptions?: Assets.RequestOptions
4 ): Promise<core.Page<TwelvelabsApi.Asset>>

Parameters:

Name	Type	Required	Description
`page`	`number`	No	A number that identifies the page to retrieve. Default: `1`.
`pageLimit`	`number`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`assetIds`	`string \| string[]`	No	Filters the response to include only assets with the specified IDs. Provide one or more asset IDs. When you specify multiple IDs, the platform returns all matching assets.
`assetTypes`	`TwelvelabsApi.AssetsListRequestAssetTypesItem \| TwelvelabsApi.AssetsListRequestAssetTypesItem[]`	No	Filters the response to include only assets of the specified types. Provide one or more asset types. When you specify multiple types, the platform returns all matching assets. Values: `image`, `video`, `audio`.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to a Page<Asset> object that allows you to iterate through the paginated asset results. For details about the Asset interface see the Create an asset section above.

The Page<T> interface contains the following properties and methods:

Name	Type	Description
`data`	`T[]`	An array containing the current page of items.
`hasNextPage()`	`boolean`	Returns whether there is a next page to load.
`getNextPage()`	`Promise<Page<T>>`	Retrieves the next page and returns the updated `Page` object.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	Allows iteration through all items across all pages using `for await` loops.

API Reference: List assets

Retrieve an asset

Description: This method retrieves details about the specified asset.

Function signature and example:

1 retrieve(
2     assetId: string,
3     requestOptions?: Assets.RequestOptions
4 ): core.HttpResponsePromise<TwelvelabsApi.Asset>

Parameters:

Name	Type	Required	Description
`assetId`	`string`	Yes	The unique identifier of the asset to retrieve.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an Asset object containing details about the specified asset. For details about the Asset interface see the Create an asset section above.

API Reference: Retrieve an asset

Delete an asset

Description: This method deletes the specified asset. This action cannot be undone.

Function signature and example:

1 delete(
2     assetId: string,
3     requestOptions?: Assets.RequestOptions
4 ): core.HttpResponsePromise<void>

Parameters:

Name	Type	Required	Description
`assetId`	`string`	Yes	The unique identifier of the asset to delete.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to void.

API Reference: Delete asset