Node.js SDK

Create video embeddings

The Resources.EmbedTask class provides methods to create embeddings for your videos.

To create video embeddings:

  1. Create a video embedding task that uploads and processes a video.
  2. Monitor the status of your task.
  3. Retrieve the embeddings once the task is completed.

Methods

Create a video embedding task

Description: This method creates a new video embedding task.

Function signature and example:

1async create(
2  modelName: string,
3  { file, url, startOffsetSec, endOffsetSec, clipLength, scopes }: CreateEmbeddingsTaskVideoParams,
4  options: RequestOptions = {},
5): Promise<Models.EmbeddingsTask | undefined>

Parameters:

NameTypeRequiredDescription
modelNamestringYesThe name of the model you want to use (example: “Marengo-retrieval-2.7”.
paramsCreateEmbeddingsTaskVideoParamsYesParameters for creating the video embedding task.
optionsRequestOptionsNoAdditional options for the request. Defaults to {}.

The CreateEmbeddingsTaskVideoParams interface defines the parameters for creating a video embedding task:

NameTypeRequiredDescription
fileBuffer | NodeJS.ReadableStream | stringNoThe video file you want to upload. This parameter can be a Buffer, a ReadableStream, or a string representing the path to the video file.
urlstringNoThe publicly accessible URL of the video file.
startOffsetSecnumberNoThe start offset in seconds from the beginning of the video where processing should begin.
endOffsetSecnumberNoThe end offset in seconds from the beginning of the video where processing should stop.
clipLengthnumberNoThe desired duration in seconds for each clip for which the platform generates an embedding.
scopesArray<'clip' | 'video'>NoSpecifies the embedding scope. Valid values are:

- ['clip']
- ['clip', 'video']

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

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

Related guide: Create video embeddings.

Retrieve the status of a video embedding task

Description: This method retrieves the status of a video embedding task.

Function signature and example:

1async status(taskId: string, options: RequestOptions = {}): Promise<Models.EmbeddingsTaskStatus>

Parameters:

NameTypeRequiredDescription
taskIdstringYesThe unique identifier of a video embedding task.
optionsRequestOptionsNoAdditional options for the request. Defaults to {}.

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

You can also use the [waitForDone] method of the Models.EmbeddingTask class to monitor the status of a video indexing task until it completes.

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

Related guide: Create video embeddings.

Retrieve video embeddings

Description: This method retrieves embeddings for a specific video embedding task. Ensure the task status is ready before retrieving your embeddings.

Function signature and example:

1async retrieve(params: Resources.RetrieveEmbeddingsTaskParams = {}, options: RequestOptions = {}): Promise<EmbeddingsTask>

Parameters:

NameTypeRequiredDescription
paramsResources.RetrieveEmbeddingsTaskParamsYesParameters for retrieving the video embedding task.
optionsRequestOptionsNoAdditional options for the request. Defaults to {}.

The Resources.RetrieveEmbeddingsTaskParams interface contains the following fields:

NameTypeRequiredDescription
embeddingOption('visual-text' | 'audio')[]NoAn optional array specifying the types of embeddings to retrieve. Each element in the array must be either visual-text or audio.

Return value: Returns a Promise that resolves to a EmbeddingsTask instance.

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

Related guide: Create video embeddings.

Error codes

This section lists the most common error messages you may encounter while using the Resources.EmbedTask class.

  • parameter_invalid
    • The video_clip_length parameter is invalid. video_clip_length should be within 2-10 seconds long
    • The video_end_offset_sec parameter is invalid. video_end_offset_sec should be greater than video_start_offset_sec