This API will be deprecated in a future version. New implementations should use the Index content API.

The Indexes.Videos interface provides methods to manage the videos you’ve uploaded to the platform.

Methods

Retrieve video information

Description: This method retrieves information about the specified video.

Function signature and example:

1 retrieve(
2   indexId: string,
3   videoId: string,
4   request?: TwelvelabsApi.indexes.VideosRetrieveRequest,
5   requestOptions?: Videos.RequestOptions,
6 ): HttpResponsePromise<TwelvelabsApi.indexes.VideosRetrieveResponse>

Parameters

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the video has been uploaded.
`videoId`	`string`	Yes	The unique identifier of the video to retrieve.
`request`	`TwelvelabsApi.indexes.VideosRetrieveRequest`	No	Request object containing optional parameters.
`requestOptions`	`Videos.RequestOptions`	No	Request-specific configuration.

The VideosRetrieveRequest interface has the following properties:

Name	Type	Required	Description
`embeddingOption`	`TwelvelabsApi.` `indexes.` `VideosRetrieveRequestEmbeddingOptionItem` or `TwelvelabsApi.` `indexes.` `VideosRetrieveRequestEmbeddingOptionItem[]`	No	Specifies which types of embeddings to retrieve. Values vary depending on the version of the model. For details, see the Embedding options section. To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model version 2.7 or later. The platform does not return embeddings if you don’t provide this parameter.
`transcription`	`boolean`	No	The parameter indicates whether to retrieve a transcription of the spoken words for the indexed video. Note that the official SDKs will support this feature in a future release.

Return value

Returns an HttpResponsePromise that resolves to a VideosRetrieveResponse object representing the retrieved video.

The VideosRetrieveResponse interface contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier of the video.
`createdAt`	`string`	The date and time, in the RFC 3339 format, that the video indexing task was created.
`updatedAt`	`string`	The date and time, in the RFC 3339 format, that the corresponding video indexing task was last updated.
`indexedAt`	`string`	The date and time, in the RFC 3339 format, that the video indexing task has been completed.
`systemMetadata`	`VideosRetrieveResponseSystemMetadata`	System-generated metadata about the video.
`userMetadata`	`Record<string, unknown>`	User-generated metadata about the video.
`hls`	`HlsObject`	HLS streaming information for the video.
`embedding`	`VideosRetrieveResponseEmbedding`	Contains the embedding and the associated information. The platform returns this field when the `embedding_option` parameter is specified in the request.
`transcription`	`TranscriptionData`	An array of transcription segments with spoken words and their timestamps.

The VideosRetrieveResponseSystemMetadata interface contains the following properties:

Name	Type	Description
`duration`	`number`	The duration of the video.
`filename`	`string`	The filename of the video.
`fps`	`number`	The frames per second of the video.
`height`	`number`	The height of the video.
`width`	`number`	The width of the video.

The HlsObject interface contains the following properties:

Name	Type	Description
`videoUrl`	`string`	The URL of the video for HLS streaming.
`thumbnailUrls`	`string[]`	An array containing the URL of the thumbnail.
`status`	`HlsObjectStatus`	The encoding status of the video file from its original format to a streamable format. Possible values: `PROCESSING`, `COMPLETE`, `CANCELED`, `ERROR`.
`updatedAt`	`string`	The date and time, in the RFC 3339 format, that the encoding status was last updated.

The VideosRetrieveResponseEmbedding interface contains the following properties:

Name	Type	Description
`modelName`	`string`	The name of the video understanding model used to create the embedding.
`videoEmbedding`	`VideosRetrieveResponseEmbeddingVideoEmbedding`	An object that contains the embeddings.

The VideosRetrieveResponseEmbeddingVideoEmbedding interface contains the following properties:

Name	Type	Description
`segments`	`VideoSegment[]`	An array of objects that contains the embeddings for each individual segment.

The VideoSegment interface extends AudioSegment and contains the following properties:

Name	Type	Description
`startOffsetSec`	`number`	The start time, in seconds, from which the platform generated the embedding.
`endOffsetSec`	`number`	The end time, in seconds, of the video segment for this embedding.
`embeddingOption`	`string`	The type of the embedding.
`embeddingScope`	`string`	The scope of the video embedding.
`float`	`number[]`	An array of floating point numbers representing the embedding. You can use this array with cosine similarity for various downstream tasks.

The TranscriptionDataItem interface contains the following properties:

Name	Type	Description
`start`	`number`	The start of the time range, expressed in seconds.
`end`	`number`	The end of the time range, expressed in seconds.
`value`	`string`	Text representing the spoken words within this time range.

API Reference

Retrieve video information page.

Description: This method iterates through a paginated list of the videos in the specified index based on the provided parameters. By default, the platform returns your videos sorted by creation date, with the newest at the top of the list.

Function signature and example:

1 async list(
2   indexId: string,
3   request?: TwelvelabsApi.indexes.VideosListRequest,
4   requestOptions?: Videos.RequestOptions
5 ): Promise<core.Page<TwelvelabsApi.VideoVector>>

Parameters

Parameter	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index for which the API will retrieve the videos.
`request.page`	`number`	No	A number that identifies the page to retrieve. Default: `1`.
`request.pageLimit`	`number`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`request.sortBy`	`string`	No	The field to sort on. Available options: `updated_at`, `created_at`. Default: `created_at`.
`request.sortOption`	`string`	No	The sorting direction. Available options: `asc`, `desc`. Default: `desc`.
`request.filename`	`string`	No	Filter by filename.
`request.duration`	`number`	No	Filter by duration. Expressed in seconds.
`request.fps`	`number`	No	Filter by frames per second.
`request.width`	`number`	No	Filter by width.
`request.height`	`number`	No	Filter by height.
`request.size`	`number`	No	Filter by size. Expressed in bytes.
`request.createdAt`	`string`	No	Filter videos by the creation date and time of their associated indexing tasks, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”).
`request.updatedAt`	`string`	No	Filter videos by the last update date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). This filter applies only to videos updated using the PUT method.
`request.userMetadata`	`Record<string, string \| number \| boolean>`	No	Filter by custom fields. You must first add user-defined metadata to your video.
`requestOptions`	`Videos.RequestOptions`	No	Request-specific configuration.

Return value

Returns a Promise that resolves to a Page<VideoVector> object that implements AsyncIterable, allowing you to iterate through the paginated list of videos.

The Page class contains the following properties and methods:

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

The VideoVector interface contains the following properties:

Name	Type	Description
`id`	`string`	The unique identifier of a video. The platform creates a new video object and assigns it a unique identifier when the video has successfully been indexed.
`createdAt`	`string`	The date and time, in the RFC 3339 format, that the video indexing task was created.
`updatedAt`	`string`	The date and time, in the RFC 3339 format, that the video indexing task object was last updated.
`indexedAt`	`string`	The date and time, in the RFC 3339 format, that the video indexing task has been completed.
`systemMetadata`	`VideoVectorSystemMetadata`	System-generated metadata about the video.

The VideoVectorSystemMetadata interface contains the following properties:

Name	Type	Description
`filename`	`string`	The filename of the video.
`duration`	`number`	The duration of the video.
`fps`	`number`	The frames per second of the video.
`width`	`number`	The width of the video.
`height`	`number`	The height of the video.
`size`	`number`	The size of the video in bytes.

API Reference

List videos.

Update video information

Description: This method updates the title and the metadata of a video.

Function signature and example:

1 update(
2   indexId: string,
3   videoId: string,
4   request?: TwelvelabsApi.indexes.VideosUpdateRequest,
5   requestOptions?: Videos.RequestOptions
6 ): HttpResponsePromise<void>

Parameters

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the video has been uploaded.
`videoId`	`string`	Yes	The unique identifier of the video to update.
`request`	[`TwelvelabsApi.indexes.VideosUpdateRequest`]	No	Parameters for updating the video information.
`requestOptions`	[`Videos.RequestOptions`]	No	Request-specific configuration.

The VideosUpdateRequest interface defines the parameters for updating a video’s information:

Name	Type	Required	Description
`userMetadata`	`Record<string, unknown>`	No	Metadata that helps you categorize your videos. 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`. If you want to store other types of data such as objects or arrays, you must convert your data into string values. You cannot override system-generated metadata fields: `duration`, `filename`, `fps`, `height`, `model_names`, `size`, `video_title`, `width`.

Return value

Returns an HttpResponsePromise that resolves to void.

API Reference

Update video information.

Delete video information

Description: This method deletes all the information about the specified video. This action cannot be undone.

Function signature and example:

1 delete(
2   indexId: string,
3   videoId: string,
4   requestOptions?: Videos.RequestOptions
5 ): HttpResponsePromise<void>

Parameters

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the video has been uploaded.
`id`	`string`	Yes	The unique identifier of the video to delete.
`requestOptions`	`Videos.RequestOptions`	No	Request-specific configuration.

Return value

Returns an HttpResponsePromise that resolves to void.

API Reference

Delete video information.