> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Manage videos > This API will be deprecated in a future version. Use the Index content API. > **Info** > > This API will be deprecated in a future version. New implementations should use the [Index content](/v1.3/sdk-reference/node-js/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**: **`Function signature`** ```javascript Function signature retrieve( indexId: string, videoId: string, request?: TwelvelabsApi.indexes.VideosRetrieveRequest, requestOptions?: Videos.RequestOptions, ): HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js"; const printSegments = (segments: TwelvelabsApi.VideoSegment[] | undefined, maxElements = 5) => { if (!segments) return; segments.forEach((segment) => { console.log( ` embeddingScope=${segment.embeddingScope} embeddingOption=${segment.embeddingOption} startOffsetSec=${segment.startOffsetSec} endOffsetSec=${segment.endOffsetSec}` ); console.log( " embeddings: ", segment.float?.slice(0, maxElements) ); }); }; const video = await client.indexes.videos.retrieve( "", "", { embeddingOption: ['visual-text', 'audio'] } ); console.log(`ID: ${video.id}`); console.log(`Created At: ${video.createdAt}`); console.log(`Updated At: ${video.updatedAt || "N/A"}`); console.log(`Indexed At: ${video.indexedAt || "N/A"}`); console.log("System metadata:"); console.log(` Filename: ${video.systemMetadata?.filename}`); console.log(` Duration: ${video.systemMetadata?.duration}`); console.log(` FPS: ${video.systemMetadata?.fps}`); console.log(` Width: ${video.systemMetadata?.width}`); console.log(` Height: ${video.systemMetadata?.height}`); if (video.userMetadata) { console.log("User metadata:"); Object.entries(video.userMetadata).forEach(([key, value]) => { console.log(`${key}: ${value}`); }); } if (video.hls) { console.log("HLS:"); console.log(` Video URL: ${video.hls.videoUrl || "N/A"}`); console.log(" Thumbnail URLs:"); (video.hls.thumbnailUrls || []).forEach((url) => { console.log(` ${url}`); }); console.log(` Status: ${video.hls.status || "N/A"}`); console.log(` Updated At: ${video.hls.updatedAt}`); } if (video.embedding) { console.log(`Model name: ${video.embedding.modelName}`); console.log("Embeddings:"); printSegments(video.embedding.videoEmbedding?.segments); } if (video.transcription) { console.log("Transcription:"); video.transcription.forEach((item) => { console.log(` ${item.start}s - ${item.end}s: ${item.value}`); }); } ``` ### 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. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section. To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model. 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. | ### 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` | User-defined metadata for 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](/v1.3/api-reference/videos/retrieve) 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**: **`Function signature`** ```javascript Function signature async list( indexId: string, request?: TwelvelabsApi.indexes.VideosListRequest, requestOptions?: Videos.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const videosPager = await client.indexes.videos.list(""); for await (const video of videosPager.data) { console.log(`ID: ${video.id}`); console.log(`Created at: ${video.createdAt}`); console.log(`Updated at: ${video.updatedAt || "N/A"}`); console.log(`Indexed at: ${video.indexedAt || "N/A"}`); if (video.systemMetadata) { console.log("System metadata:"); console.log(` Filename: ${video.systemMetadata.filename || "N/A"}`); console.log(` Duration: ${video.systemMetadata.duration || "N/A"}`); console.log(` FPS: ${video.systemMetadata.fps || "N/A"}`); console.log(` Width: ${video.systemMetadata.width || "N/A"}`); console.log(` Height: ${video.systemMetadata.height || "N/A"}`); console.log(` Size: ${video.systemMetadata.size || "N/A"}`); } console.log("---"); } ``` ### 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` | 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` 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` | Retrieves the next page and returns the updated `Page` object. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `Symbol.asyncIterator` | `AsyncIterator` | 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](/v1.3/api-reference/videos/list). ## Update video information **Description**: This method updates the title and the metadata of a video. **Function signature and example**: **`Function signature`** ```javascript Function signature update( indexId: string, videoId: string, request?: TwelvelabsApi.indexes.VideosUpdateRequest, requestOptions?: Videos.RequestOptions ): HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.indexes.videos.update(index.id!, videoId!, { userMetadata: { from_sdk: true }, }); ``` ### 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` | No | Metadata that helps you categorize your videos. You can specify a list of keys and values. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. 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](/v1.3/api-reference/videos/update). ## Delete video information **Description**: This method deletes all the information about the specified video. This action cannot be undone. **Function signature and example**: **`Function signature`** ```javascript Function signature delete( indexId: string, videoId: string, requestOptions?: Videos.RequestOptions ): HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.indexes.videos.delete("", ""); ``` ### 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](/v1.3/api-reference/videos/delete).