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.

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.

Wait for a video embedding task to complete

Description: This method waits until a video embedding task is completed by periodically checking its status. If you provide a callback function, it calls the function after each status update with the current task object, allowing you to monitor progress.

Function signature and example:

1async waitForDone(
2  sleepInterval: number = 5000,
3  callback?: (task: EmbeddingsTask) => void,
4): Promise<string>

Parameters

NameTypeRequiredDescription
sleepIntervalnumberNoThe time in milliseconds to wait between status checks. Must be greater than 0. Default is 5000.
callback(task: EmbeddingsTask) => voidNoAn optional function to call after each status check. It receives the current task object. Use this to monitor progress.

Return value: A Promise that resolves to a string representing the final status of the task (“ready” or “failed”).

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