The Assets class 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.

For URL uploads larger than 200 MB, check the asset status using the assets.retrieve method until status is ready before proceeding.

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.

Upload limits:

Video and audio, local files: Up to 200 MB
Video and audio, public URLs: Up to 4 GB
Images: Up to 5 MB

Additional requirements depend on your workflow:

Search: Marengo requirements
Video analysis: Pegasus requirements
Entity search: Marengo image requirements
Create embeddings: Marengo requirements

Note

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

Function signature and example:

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

Parameters

Name	Type	Required	Description
`request`	`TwelvelabsApi.AssetsCreateRequest`	Yes	Parameters for creating an asset.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.AssetsCreateRequest interface has the following properties:

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`. Local video and audio files support up to 200 MB. Image files support up to 5 MB.
`url`	`string`	No	The publicly accessible URL of a media file 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 5 MB.
`filename`	`string`	No	The optional filename of the asset. If not provided, the platform determines the filename from the file or URL.
`enableHls`	`boolean`	No	When set to `true`, the platform generates an HLS playlist and segments for streaming. Applicable to video and audio assets only. Default: `false`.
`enableThumbnail`	`boolean`	No	When set to `true`, the platform generates thumbnail images from the uploaded content. Default: `false`.

Return value

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

The TwelvelabsApi.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), `multipart` (uploaded using the multipart upload flow).
`status`	`TwelvelabsApi.AssetStatus`	Indicates the current status of the asset. Values: `failed` (the platform failed 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.
`size`	`number`	The file size of the asset in bytes. This field is absent while the asset is still being processed.
`duration`	`number`	The duration of the asset in seconds. Only present for video and audio assets. This field is absent for image assets or while the asset is still being processed.
`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.AssetDetail>>

Parameters

Name	Type	Required	Description
`request`	`TwelvelabsApi.AssetsListRequest`	Yes	Parameters for creating the index.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.AssetsListRequest interface has the following properties:

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`.
`filename`	`string`	No	Filters the response to include only assets whose filename contains the specified string. The match is case-insensitive and supports partial matching.

Return value

Returns a Promise that resolves to a Page<TwelvelabsApi.AssetDetail> object that allows you to iterate through the paginated asset results. The AssetDetail interface extends Asset with additional fields for HLS streaming and thumbnail details. For details about the TwelvelabsApi.AssetDetail interface, see the Retrieve an asset section below.

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.AssetDetail>

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 an HttpResponsePromise that resolves to a TwelvelabsApi.AssetDetail object containing details about the specified asset.

The TwelvelabsApi.AssetDetail interface extends TwelvelabsApi.Asset (documented in the Create an asset section above) with the following additional properties:

Name	Type	Description
`hls`	`TwelvelabsApi.AssetHls`	HLS streaming details for the asset. Present only when HLS generation has been requested.
`thumbnail`	`TwelvelabsApi.AssetThumbnail`	Thumbnail details for the asset. Present only when thumbnail generation has been requested.

The TwelvelabsApi.AssetHls interface contains the following properties:

Name	Type	Description
`manifestUrl`	`string`	The URL of the HLS manifest file for streaming. Only present when the status is `ready`.
`status`	`TwelvelabsApi.AssetHlsStatus`	The status of the HLS stream. Values: `pending` (the platform has not yet started HLS generation), `processing` (the platform is generating HLS segments), `ready` (the HLS stream is ready for playback), `error` (HLS generation failed).

The TwelvelabsApi.AssetThumbnail interface contains the following properties:

Name	Type	Description
`representativeUrl`	`string`	The URL of the representative thumbnail image. Only present when the status is `ready`.
`status`	`TwelvelabsApi.AssetThumbnailStatus`	The status of the thumbnail. Values: `pending` (the platform has not yet started thumbnail generation), `processing` (the platform is generating the thumbnail), `ready` (the thumbnail is ready), `error` (thumbnail generation failed).

API Reference

Retrieve an asset

Delete an asset

Description: This method deletes the specified asset. This action cannot be undone. By default, the platform checks whether any indexed assets reference the asset. If references exist, the request fails with a 409 Conflict error. Set the force parameter to true to delete the asset regardless.

Function signature and example:

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

Parameters

Name	Type	Required	Description
`assetId`	`string`	Yes	The unique identifier of the asset to delete.
`request`	`TwelvelabsApi.AssetsDeleteRequest`	No	Parameters for deleting an asset.
`requestOptions`	`Assets.RequestOptions`	No	Request-specific configuration.

The TwelvelabsApi.AssetsDeleteRequest interface has the following properties:

Name	Type	Required	Description
`force`	`boolean`	No	When set to `true`, the platform deletes the asset even if indexed assets reference it. When set to `false` or omitted, the request fails with `409 Conflict` if references exist. Default: `false`.

Return value

Returns an HttpResponsePromise that resolves to void.

API Reference

Delete asset