The Resources.Video class 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:

async retrieve(
  indexId: string,
  id: string,
  { embed }: RetrieveVideoParams = {},
  options: RequestOptions = {},
): Promise<Models.Video>

const printSegments = (segments: SegmentEmbedding[], maxElements = 5) => {
  segments.forEach((segment) => {
    console.log(
      `  embedding_scope=${segment.embeddingScope} start_offset_sec=${segment.startOffsetSec} end_offset_sec=${segment.endOffsetSec}`
    );
    console.log(
      "  embeddings: ",
      segment.embeddingsFloat.slice(0, maxElements)
    );
  });
};

const video = await client.index.video.retrieve(
  "<YOUR_INDEX_ID>",
  "<YOUR_VIDEO_ID>",
  { embed: true }
);
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}`);
console.log(`  Size: ${video.systemMetadata.size}`);
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.source) {
console.log("Source:");
console.log(`  Type: ${video.source.type}`);
console.log(`  Name: ${video.source.name}`);
console.log(`  URL: ${video.source.url || "N/A"}`);
}
if (video.embedding) {
    console.log(`Engine name: ${video.embedding.engineName}`);
    console.log("Embeddings:");
    printSegments(video.embedding.videoEmbedding.segments);
}

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 retrieve.
`embed`	`RetrieveVideoParams`	No	Set this parameter to `true` to retrieve the video embedding in the response.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

Return value: Returns a Promise that resolves to a Models.Video instance.

API Reference: For a description of each field in the request and response, see the Retrieve video information page.

List videos with direct pagination

Description: This method returns a paginated list of the videos in the specified index based on the provided parameters. Choose this method mainly when the total number of items is manageable, or you must fetch a single page of results. By default, the platform returns your videos sorted by their upload date, with the newest at the top of the list.

Function signature and example:

async list(
  indexId: string,
  {
    id,
    size,
    width,
    height,
    duration,
    fps,
    createdAt,
    updatedAt,
    ...restParams
  }: ListVideoParams = {},
  options: RequestOptions = {},
): Promise<Models.Video[]>

const listParams = {
id: "66ea61c40679760c1fc6a114",
filename: "example_video.mp4",
size: 1024,
width: 1280,
height: 720,  // Example: 720p to 1080p
duration: 20,  // Example: 1 minute to 5 minutes
fps: 24,
userMetadata: {
    category: "nature"
},
createdAt: "2024-09-17T07:53:46.365Z",
updatedAt: "2024-09-17T07:53:46.365Z",
page: 1,
pageLimit: 5,
sortBy: "created_at",
sortOption: "desc"
};

const videos = await client.index.video.list("66e9358a808d95368f6f7a7c", listParams)
videos.forEach(video => {
console.log(`ID: ${video.id}`);
console.log(`  Created at: ${video.createdAt}`);
console.log(`  Updated at: ${video.updatedAt || "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}`);
console.log(`    Size: ${video.systemMetadata.size}`);
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.source) {
    console.log("  Source:");
    console.log(`    Type: ${video.source.type}`);
    console.log(`    Name: ${video.source.name}`);
    console.log(`    URL: ${video.source.url || "N/A"}`);
}
});

Parameters:

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the video has been uploaded.
`params`	`ListVideoParams`	No	Parameters for retrieving the list of videos. Defaults to `{}`. If you don't specify the `page` parameter, the platform returns the first page of results.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The ListVideoParams interface extends the PageOptions interface and defines the parameters for listing videos:

Name	Type	Required	Description
`id`	`string`	No	Filter by the unique identifier of a video.
`filename`	`string`	No	Filter by filename.
`size`	number \	Record`<string, number>`	No
`width`	number \	Record`<string, number>`	No
`height`	number \	Record`<string, number>`	No
`duration`	number \	Record`<string, number>`	No
`fps`	number \	Record`<string, number>`	No
`userMetadata`	`Record<string, any>`	No	Filter by metadata associated with the video. This field can contain any key-value pairs.
`createdAt`	string \	Record`<string, string>`	No
`updatedAt`	string \	Record`<string, string>`	No

The following properties are inherited from the PageOptions interface:

Name	Type	Required	Description
`page`	`number`	No	The page number for pagination.
`pageLimit`	`number`	No	The number of items per page.
`sortBy`	`'created_at' \	'updated_at'`	No
`sortOption`	`'asc' \	'desc'`	No

Return value: Returns a Promise that resolves to an array of Models.Video instances.

API Reference: For a description of each field in the request and response, see the List videos page.

Related guides:

List videos with iterative pagination

Description: This method iterates through a paginated list of the videos in the specified index based on the provided parameters. Choose this method mainly when your application must retrieve a large number of items. By default, the API returns your videos sorted by creation date, with the newest at the top of the list.

Function signature and example:

async listPagination(
  indexId: string,
  {
    id,
    size,
    width,
    height,
    duration,
    fps,
    createdAt,
    updatedAt,
    ...restParams
  }: ListVideoParams = {},
  options: RequestOptions = {},
): Promise<Models.VideoListWithPagination>

function printPage(page) {
  page.forEach(video => {
    console.log(video)
    console.log(`ID: ${video.id}`);
    console.log(`  Created at: ${video.createdAt}`);
    console.log(`  Updated at: ${video.updatedAt || "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}`);
    console.log(`    Size: ${video.systemMetadata.size}`);
    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.source) {
      console.log("  Source:");
      console.log(`    Type: ${video.source.type}`);
      console.log(`    Name: ${video.source.name}`);
      console.log(`    URL: ${video.source.url || "N/A"}`);
    }
  });
}

const listParams = {
id: "66ea61c40679760c1fc6a114",
filename: "example_video.mp4",
size: 1024,
width: 1280,
height: 720,  // Example: 720p to 1080p
duration: 20,  // Example: 1 minute to 5 minutes
fps: 24,
userMetadata: {
    category: "nature"
},
createdAt: "2024-09-17T07:53:46.365Z",
updatedAt: "2024-09-17T07:53:46.365Z",
page: 1,
pageLimit: 5,
sortBy: "created_at",
sortOption: "desc"
};

// Fetch the initial page of results
const videoPaginator = await client.index.video.listPagination("66e9358a808d95368f6f7a7c", listParams);

// Print the first page of results
printPage(videoPaginator.data);

// Iterate through subsequent pages
while (true) {
const nextPage = await videoPaginator.next();
if (!nextPage) {
    break;
}
printPage(nextPage);
}

Parameters:

Name	Type	Required	Description
`params`	`ListVideoParams`	No	Parameters for retrieving the list of videos. Defaults to `{}`. If you don't specify the `page` parameter, the platform returns the first page of results.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The ListVideoParams interface extends the PageOptions interface and defines the parameters for listing videos:

Name	Type	Required	Description
`id`	`string`	No	Filter by the unique identifier of a video.
`filename`	`string`	No	Filter by filename.
`size`	number \	Record`<string, number>`	No
`width`	number \	Record`<string, number>`	No
`height`	number \	Record`<string, number>`	No
`duration`	number \	Record`<string, number>`	No
`fps`	number \	Record`<string, number>`	No
`userMetadata`	Record`<string, any>`	No	Filter by metadata associated with the video. This field can contain any key-value pairs.
`createdAt`	string \	Record`<string, string>`	No
`updatedAt`	string \	Record`<string, string>`	No

The following properties are inherited from the PageOptions interface:

Name	Type	Required	Description
`page`	`number`	No	The page number for pagination.
`pageLimit`	`number`	No	The number of items per page.
`sortBy`	`'created_at' \	'updated_at'`	No
`sortOption`	`'asc' \	'desc'`	No

Return value: Returns a Promise that resolves to an array of VideoListWithPagination instances.

📘
Note:
To retrieve subsequent pages of results, use the async iterator protocol:

Invoke the next method of the VideoListWithPagination object.

Repeat this call until the method returns a promise that resolves tonull, indicating no more pages exist.

API Reference: For a description of each field in the request and response, see the List videos page.

Related guides:

Update video information

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

Function signature and example:

async update(
  indexId: string,
  id: string,
  { userMetadata }: UpdateVideoParams,
  options: RequestOptions = {},
): Promise<void>

await client.index.video.update('<YOUR_INDEX_ID>', '<YOUR_VIDEO_ID>', { 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.
`id`	`string`	Yes	The unique identifier of the video.
`params`	`UpdateVideoParams`	Yes	Parameters for updating the video information.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The UpdateVideoParams interface defines the parameters for updating a video's information:

Name	Type	Required	Description
`userMetadata`	`Record<string, any>`	No	The metadata you want to update or add.. This parameter can contain any key-value pairs. Note that only the provided properties are modified; the omitted properties remain unchanged.

Return value: Returns a Promise that resolves to void.

API Reference: For a description of each field in the request, see the Update video information page.

Delete video information

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

Function signature and example:

async delete(indexId: string, id: string, options: RequestOptions = {}): Promise<void>

await client.index.video.delete('YOUR_INDEX_ID');

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.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

Return value: Returns a Promise that resolves to void.

API Reference: Delete video information.