Manage videos

The IndexesVideosWrapperclass 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:

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

Parameters:

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to which the video has been uploaded.
videoIdstringYesThe unique identifier of the video to retrieve.
requestTwelvelabsApi.indexes.VideosRetrieveRequestNoRequest object containing optional parameters.
requestOptionsVideos.RequestOptionsNoRequest-specific configuration.

The VideosRetrieveRequest interface has the following properties:

NameTypeRequiredDescription
embeddingOptionTwelvelabsApi.
indexes.
VideosRetrieveRequestEmbeddingOptionItem or TwelvelabsApi.
indexes.
VideosRetrieveRequestEmbeddingOptionItem[]
NoSpecifies which types of embeddings to retrieve. You can include one or more of the following values:
- visual-text: Returns visual embeddings optimized for text search.
- audio: Returns audio embeddings.

To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model version 2.7 or later. For details on enabling this model for an index, see the Create an index page.

The platform does not return embeddings if you don’t provide this parameter.

The values you specify in embedding_option must be included in the model_options defined when the index was created. For example, if model_options is set to visual, you cannot set embedding_option to audio or both visual-text and audio.
transcriptionbooleanNoThe 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 a HttpResponsePromise that resolves to a VideosRetrieveResponse object representing the retrieved video.

The VideosRetrieveResponse interface contains the following properties:

NameTypeDescription
idstringThe unique identifier of the video.
createdAtstringThe date and time, in the RFC 3339 format, that the video indexing task was created.
updatedAtstringThe date and time, in the RFC 3339 format, that the corresponding video indexing task was last updated.
indexedAtstringThe date and time, in the RFC 3339 format, that the video indexing task has been completed.
systemMetadataVideosRetrieveResponseSystemMetadataSystem-generated metadata about the video.
userMetadataRecord<string, unknown>User-generated metadata about the video.
hlsHlsObjectHLS streaming information for the video.
embeddingVideosRetrieveResponseEmbeddingContains the embedding and the associated information. The platform returns this field when the embedding_option parameter is specified in the request.
transcriptionTranscriptionDataAn array of transcription segments with spoken words and their timestamps.

The VideosRetrieveResponseSystemMetadata interface contains the following properties:

NameTypeDescription
durationnumberThe duration of the video.
filenamestringThe filename of the video.
fpsnumberThe frames per second of the video.
heightnumberThe height of the video.
widthnumberThe width of the video.

The HlsObject interface contains the following properties:

NameTypeDescription
videoUrlstringThe URL of the video for HLS streaming.
thumbnailUrlsstring[]An array containing the URL of the thumbnail.
statusHlsObjectStatusThe encoding status of the video file from its original format to a streamable format. Possible values: PROCESSING, COMPLETE, CANCELED, ERROR.
updatedAtstringThe date and time, in the RFC 3339 format, that the encoding status was last updated.

The VideosRetrieveResponseEmbedding interface contains the following properties:

NameTypeDescription
modelNamestringThe name of the video understanding model used to create the embedding.
videoEmbeddingVideosRetrieveResponseEmbeddingVideoEmbeddingAn object that contains the embeddings.

The VideosRetrieveResponseEmbeddingVideoEmbedding interface contains the following properties:

NameTypeDescription
segmentsVideoSegment[]An array of objects that contains the embeddings for each individual segment.

The VideoSegment interface extends AudioSegment and contains the following properties:

NameTypeDescription
startOffsetSecnumberThe start time, in seconds, from which the platform generated the embedding.
endOffsetSecnumberThe end time, in seconds, of the video segment for this embedding.
embeddingOptionstringThe type of the embedding.
embeddingScopestringThe scope of the video embedding.
floatnumber[]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:

NameTypeDescription
startnumberThe start of the time range, expressed in seconds.
endnumberThe end of the time range, expressed in seconds.
valuestringText representing the spoken words within this time range.

API Reference: Retrieve video information page.

List videos

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:

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

Parameters:

ParameterTypeRequiredDescription
indexIdstringYesThe unique identifier of the index for which the API will retrieve the videos.
request.pagenumberNoA number that identifies the page to retrieve. Default: 1.
request.pageLimitnumberNoThe number of items to return on each page. Default: 10. Max: 50.
request.sortBystringNoThe field to sort on. Available options: updated_at, created_at. Default: created_at.
request.sortOptionstringNoThe sorting direction. Available options: asc, desc. Default: desc.
request.filenamestringNoFilter by filename.
request.durationnumberNoFilter by duration. Expressed in seconds.
request.fpsnumberNoFilter by frames per second.
request.widthnumberNoFilter by width.
request.heightnumberNoFilter by height.
request.sizenumberNoFilter by size. Expressed in bytes.
request.createdAtstringNoFilter videos by the creation date and time of their associated indexing tasks, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”).
request.updatedAtstringNoFilter 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.userMetadataRecord<string, string | number | boolean>NoFilter by custom fields. You must first add user-defined metadata to your video.
requestOptionsVideos.RequestOptionsNoRequest-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:

NameTypeDescription
dataT[]An array containing the current page of items.
getNextPage()Promise<this>Retrieves the next page and returns the updated Page object.
hasNextPage()booleanReturns 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:

NameTypeDescription
idstringThe 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.
createdAtstringThe date and time, in the RFC 3339 format, that the video indexing task was created.
updatedAtstringThe date and time, in the RFC 3339 format, that the video indexing task object was last updated.
indexedAtstringThe date and time, in the RFC 3339 format, that the video indexing task has been completed.
systemMetadataVideoVectorSystemMetadataSystem-generated metadata about the video.

The VideoVectorSystemMetadata interface contains the following properties:

NameTypeDescription
filenamestringThe filename of the video.
durationnumberThe duration of the video.
fpsnumberThe frames per second of the video.
widthnumberThe width of the video.
heightnumberThe height of the video.
sizenumberThe 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:

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

Parameters:

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to which the video has been uploaded.
videoIdstringYesThe unique identifier of the video to update.
request[TwelvelabsApi.indexes.VideosUpdateRequest]NoParameters for updating the video information.
requestOptions[Videos.RequestOptions]NoRequest-specific configuration.

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

NameTypeRequiredDescription
userMetadataRecord<string, unknown>NoMetadata 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:

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

Parameters:

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to which the video has been uploaded.
idstringYesThe unique identifier of the video to delete.
requestOptionsVideos.RequestOptionsNoRequest-specific configuration.

Return value: Returns an HttpResponsePromise that resolves to void.

API Reference: Delete video information.