A video indexing task represents a request to upload and index a video. The Resources.Task class provides methods to manage your video indexing tasks.

Methods

Create a video indexing task

Description: This method creates a new video indexing task that uploads and indexes a video.

Function signature and example:

async create(body: CreateTaskParams, options: RequestOptions = {}): Promise<Models.Task>

import { Task } from 'twelvelabs-js';

const task = await client.task.create({
  indexId: '<YOUR_INDEX_ID>',
  file: '<YOUR_FILE_PATH>',
  transcriptionFile: '<YOUR_TRANSCRIPTION_FILE>'),
});
console.log(`Task ID:${task.id}`);
await task.waitForDone(500, (task: Task) => {
  console.log(`  Status=${task.status}`);
});

if (task.status !== 'ready') {
  throw new Error(`Indexing failed with status ${task.status}`);
}
console.log(`Video ID: ${task.videoId}`);

Parameters:

Name	Type	Required	Description
`body`	`CreateTaskParams`	Yes	Parameters for creating the new video indexing task.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The CreateTaskParams interface defines the parameters for creating a new video indexing task:

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the video will be uploaded.
`file`	`Buffer \| NodeJS.ReadableStream \| string`	No	The file you want to upload. This parameter can be a `Buffer`, a `ReadableStream`, or a string representing the path to the file.
`url`	`string`	No	The publicly accessible URL of the video you want to upload.
`transcriptionFile`	`Buffer \| NodeJS.ReadableStream \| string`	No	The transcription file. This parameter can be a `Buffer`, a `ReadableStream`, or a string representing the path to the file.
`transcriptionUrl`	`string`	No	The URL of the transcription file.
`language`	`string`	No	The language of the video.
`disableVideoStream`	`boolean`	No	Indicates if the platform stores the video for streaming.

Return value: Returns a Promise that resolves to a Models.Task instance representing the newly created video indexing task.

📘
Note:
As shown in the example code above, you can use the waitForDone method of the Models.Task class to monitor the status of a video indexing task until it completes.

API Reference: For a description of each field in the request and response, see the Create a video indexing task page.

Related guide: Upload single videos.

Retrieve a video indexing task

Description: This method retrieves the details of a specific video indexing task.

Function signature and example:

async retrieve(id: string, options: RequestOptions = {}): Promise<Models.Task>

const retrievedTask = await client.task.retrieve("<YOUR_TASK_ID>");
console.log(`Task ID=${retrievedTask.id}`);
console.log(`Index ID: ${retrievedTask.indexId}`);
console.log(`Video ID: ${retrievedTask.videoId}`);
console.log(`Estimated time: ${retrievedTask.estimatedTime}`);
console.log(`Status: ${retrievedTask.status}`);

console.log("Metadata:");
for (const [key, value] of Object.entries(retrievedTask.metadata)) {
  console.log(`  ${key}: ${value}`);
}

if (retrievedTask.hls) {
  console.log("HLS:");
  console.log(`  Video URL: ${retrievedTask.hls.videoUrl}`);
  console.log("  Thumbnail URLs:");
  for (const url of retrievedTask.hls.thumbnailUrls || []) {
    console.log(`    ${url}`);
  }
  console.log(`  Status: ${retrievedTask.hls.status}`);
  console.log(`  Updated at: ${retrievedTask.hls.updatedAt}`);
}

if (retrievedTask.process) {
  console.log("Process:");
  console.log(`  Percentage: ${retrievedTask.process.percentage}%`);
  console.log(`  Remaining Seconds: ${retrievedTask.process.remainSeconds}`);
}

console.log(`Created at: ${retrievedTask.createdAt}`);
console.log(`Updated at: ${retrievedTask.updatedAt}`);

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the task to retrieve.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

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

API Reference: For a description of each field in the response, see the Retrieve a video indexing task.

List video indexing tasks with direct pagination

Description: This method returns a list of the video indexing tasks in your account. By default, the platform returns your video indexing tasks sorted by creation date, with the newest at the top of the list. Choose this method mainly when the total number of items is manageable, or you must fetch a single page of results.

Function signature and example:

async list(
  { id, createdAt, updatedAt, ...restParams }: ListTaskParams = {},
  options: RequestOptions = {},
): Promise<Models.Task[]>

const listParams = {
  id: '<YOUR_TASK_ID>',
  index_id: '<YOUR_INDEX_ID>',
  filename: '<YOUR_FILENAME>',
  duration: 20,
  width:1920,
  height: 1080,
  sortBy: 'updated_at',
  sortOption: 'asc',
  estimatedTime: '2024-09-17T07:55:22.125Z',
  page: 2,
  pageLimit: 5,
};
const tasks = await client.task.list(listParams)
tasks.forEach(task => {
  console.log(`Task ID=${task.id}`);
  console.log(`Index ID: ${task.indexId}`);
  console.log(`Video ID: ${task.videoId}`);
  console.log(`Estimated time: ${task.estimatedTime}`);
  console.log(`Status: ${task.status}`);
  
  console.log("Metadata:");
  for (const [key, value] of Object.entries(task.metadata)) {
    console.log(`  ${key}: ${value}`);
  }

  if (task.hls) {
    console.log("HLS:");
    console.log(`  Video URL: ${task.hls.videoUrl}`);
    console.log("  Thumbnail URLs:");
    for (const url of task.hls.thumbnailUrls || []) {
      console.log(`    ${url}`);
    }
    console.log(`  Status: ${task.hls.status}`);
    console.log(`  Updated at: ${task.hls.updatedAt}`);
  }

  if (task.process) {
    console.log("Process:");
    console.log(`  Percentage: ${task.process.percentage}%`);
    console.log(`  Remaining Seconds: ${task.process.remainSeconds}`);
  }

  console.log(`Created at: ${task.createdAt}`);
  console.log(`Updated at: ${task.updatedAt}`);
});

Parameters:

Name	Type	Required	Description
`params`	`ListTaskParams`	No	Parameters for filtering the list of tasks. Defaults to `{}`.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The ListTaskParams interface extends the PageOptions interface and defines the parameters for listing video indexing tasks:

Name	Type	Required	Description
`id`	`string`	No	Filter by the unique identifier of a video indexing task.
`indexId`	`string`	No	Filter by the unique identifier of an index.
`filename`	`string`	No	Filter by the name of a video file.
`duration`	`number`	No	Filter by the duration of a video expressed in seconds.
`width`	`number`	No	Filter by the width of a video.
`height`	`number`	No	Filter by the height of a video.
`createdAt`	`string \| Record<string, string>`	No	Filter by the creation date of a video indexing task. This parameter can be a string or an object with string keys and values for range queries.
`updatedAt`	`string \| Record<string, string>`	No	Filter by the last update date of a video indexing task. This parameter can be a string or an object with string keys and values for range queries.
`estimatedTime`	`number`	No	Filter by the estimated processing time, expressed in seconds.

The following properties are inherited from PageOptions:

Name	Type	Required	Description
`page`	`number`	No	Page number for pagination. Defaults to 1.
`pageLimit`	`number`	No	Number of items per page. Defaults to 10.
`sortBy`	`'createdAt' \| 'updatedAt'`	No	Field to sort by ("createdAt" or "updatedAt"). Defaults to "createAt".
`sortOption`	`'asc' \| 'desc'`	No	Sort order ("asc" or "desc"). Defaults to "desc".

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

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

Related guides:

List video indexing tasks with iterative pagination

Description: This method returns a paginated list of the video indexing tasks in your account. Choose this method mainly when your application must retrieve a large number of items. By default, the platform returns your video indexing tasks sorted by creation date, with the newest at the top of the list.

Function signature and example:

async listPagination(
  { id, createdAt, updatedAt, ...restParams }: ListTaskParams = {},
  options: RequestOptions = {},
): Promise<Models.TaskListWithPagination>

function printPage(page) {
  page.forEach(task => {
    console.log(`Task ID=${task.id}`);
    console.log(`Index ID: ${task.indexId}`);
    console.log(`Video ID: ${task.videoId}`);
    console.log(`Estimated time: ${task.estimatedTime}`);
    console.log(`Status: ${task.status}`);
    
    console.log("Metadata:");
    for (const [key, value] of Object.entries(task.metadata)) {
      console.log(`  ${key}: ${value}`);
    }
  
    if (task.hls) {
      console.log("HLS:");
      console.log(`  Video URL: ${task.hls.videoUrl}`);
      console.log("  Thumbnail URLs:");
      for (const url of task.hls.thumbnailUrls || []) {
        console.log(`    ${url}`);
      }
      console.log(`  Status: ${task.hls.status}`);
      console.log(`  Updated at: ${task.hls.updatedAt}`);
    }
  
    if (task.process) {
      console.log("Process:");
      console.log(`  Percentage: ${task.process.percentage}%`);
      console.log(`  Remaining Seconds: ${task.process.remainSeconds}`);
    }
  
    console.log(`Created at: ${task.createdAt}`);
    console.log(`Updated at: ${task.updatedAt}`);
  });
}
const listParams = {
    id: '<YOUR_TASK_ID>',
    index_id: '<YOUR_INDEX_ID>',
    filename: '<YOUR_FILENAME>',
    duration: 20,
    width:1920,
    height: 1080,
    sortBy: 'updated_at',
    sortOption: 'asc',
    createdAt: '2024-09-17T07:53:46.365Z',
    updatedAt: '2024-09-17T07:53:46.365Z',
    estimatedTime: '2024-09-17T07:55:22.125Z',
    page: 2,
    pageLimit: 5,
};

// Fetch the initial page of results
const taskPaginator = await client.task.listPagination(listParams);

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

// Iterate through subsequent pages
while (true) {
const nextTaskPage = await taskPaginator.next();
if (!nextTaskPage) {
    console.log('No more pages of index results available');
    break;
}
printPage(nextTaskPage);
}

Parameters

Name	Type	Required	Description
`params`	`ListTaskParams`	No	Parameters for filtering and paginating the list of tasks. Defaults to `{}`.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

The ListTaskParams interface extends the PageOptions interface and defines the parameters for listing video indexing tasks:

Name	Type	Required	Description
`id`	`string`	No	Filter by the unique identifier of a video indexing task.
`indexId`	`string`	No	Filter by the unique identifier of an index.
`filename`	`string`	No	Filter by the name of a video file.
`duration`	`number`	No	Filter by the duration of a video expressed in seconds.
`width`	`number`	No	Filter by the width of a video.
`height`	`number`	No	Filter by the height of a video.
`createdAt`	`string \| Record<string, string>`	No	Filter by the creation date of a video indexing task. This parameter can be a string or an object with string keys and values for range queries.
`updatedAt`	`string \| Record<string, string>`	No	Filter by the last update date of a video indexing task. This parameter can be a string or an object with string keys and values for range queries.
`estimatedTime`	`number`	No	Filter by the estimated processing time, expressed in seconds.

The following properties are inherited from PageOptions:

Name	Type	Required	Description
`page`	`number`	No	Page number for pagination. Defaults to 1.
`pageLimit`	`number`	No	Number of items per page. Defaults to 10.
`sortBy`	`'createdAt' \| 'updatedAt'`	No	Field to sort by ("createdAt" or "updatedAt"). Defaults to "createdAt".
`sortOption`	`'asc' \| 'desc'`	No	Sort order ("asc" or "desc"). Defaults to "desc".

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

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

Invoke the nextmethod of the TaskListWithPagination 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 video indexing tasks page.

Related guides:

Delete a video indexing task

Description: This method deletes an existing video indexing task.

Function signature and example:

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

await client.task.delete('<YOUR_TASK_ID>');

Parameters:

Name	Type	Required	Description
`id`	`string`	Yes	The unique identifier of the video indexing task to delete.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

Return value: Returns a Promise that resolves to void. This method doesn't return any data upon successful completion.

API Refference: Delete a video indexing task.

Make a cloud-to-cloud-transfer

Description: This method makes a cloud-to-cloud transfer. Cloud-to-cloud transfers allow you to upload multiple videos at once by grouping multiple video indexing operations in a single API call. Initially, this feature is supported for the "us-west-2" region of AWS S3.

Function signature and example:

async transfer(file: Buffer | NodeJS.ReadableStream, options: RequestOptions = {}): Promise<void>

client.task.transfer(fs.createReadStream('<YOUR_JSON_FILE>'));

Parameters

Name	Type	Required	Description
`file`	`Buffer \| NodeJS.ReadableStream`	Yes	A JSON file that contains a list of the files you wish to upload.
`options`	`RequestOptions`	No	Additional options for the request. Defaults to `{}`.

Return value: Returns a Promise that resolves to void. This method doesn't return any data upon successful completion.

API Reference: For a description of each field in the request, see the Make a cloud-to-cloud transfer page.

Related guide: Cloud-to-cloud transfers

Upload videos

Methods

Create a video indexing task

📘
Note:

Retrieve a video indexing task

List video indexing tasks with direct pagination

List video indexing tasks with iterative pagination

📘
Note:

Delete a video indexing task

Make a cloud-to-cloud-transfer

Methods

Create a video indexing task

📘Note:

Retrieve a video indexing task

List video indexing tasks with direct pagination

List video indexing tasks with iterative pagination

📘Note:

Delete a video indexing task

Make a cloud-to-cloud-transfer

📘
Note:

📘
Note: