The Resources.EmbedTask
class provides methods to create embeddings for your videos.
To create video embeddings:
- Create a video embedding task that uploads and processes a video.
- Monitor the status of your task.
- 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:
async create(
engineName: string,
{ file, url, startOffsetSec, endOffsetSec, clipLength, scopes }: CreateEmbeddingsTaskVideoParams,
options: RequestOptions = {},
): Promise<Models.EmbeddingsTask | undefined>
const params = {
file: '<YOUR_VIDEO_FILE>',
url: '<YOUR_VIDEO_URL>',
startOffsetSec: 5,
endOffsetSec: 15,
clipLength: 5,
scopes: ['clip', 'video'],
};
const task = await client.embed.task.create('Marengo-retrieval-2.6', params);
console.log(`Task ID: ${task.id}`);
console.log(`Engine Name: ${task.engineName}`);
console.log(`Status: ${task.status}`);
Parameters:
Name | Type | Required | Description |
---|---|---|---|
engineName | string | Yes | The name of the engine you want to use (example: "Marengo-retrieval-2.6". |
params | CreateEmbeddingsTaskVideoParams | Yes | Parameters for creating the video embedding task. |
options | RequestOptions | No | Additional options for the request. Defaults to {} . |
The CreateEmbeddingsTaskVideoParams
interface defines the parameters for creating a video embedding task:
Name | Type | Required | Description |
---|---|---|---|
file | Buffer | NodeJS.ReadableStream | string | No | The video file you want to upload. This parameter can be a Buffer , a ReadableStream , or a string representing the path to the video file. |
url | string | No | The publicly accessible URL of the video file. |
startOffsetSec | number | No | The start offset in seconds from the beginning of the video where processing should begin. |
endOffsetSec | number | No | The end offset in seconds from the beginning of the video where processing should stop. |
clipLength | number | No | The desired duration in seconds for each clip for which the platform generates an embedding. |
scopes | Array<'clip' | 'video'> | No | Specifies 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:
async status(taskId: string, options: RequestOptions = {}): Promise<Models.EmbeddingsTaskStatus>
const task = await client.embed.task.status('<YOUR_TASK_ID>')
console.log(`Task ID: ${task.id}`);
console.log(`Engine Name: ${task.engineName}`);
console.log(`Status: ${task.status}`);
Parameters:
Name | Type | Required | Description |
---|---|---|---|
taskId | string | Yes | The unique identifier of a video embedding task. |
options | RequestOptions | No | Additional options for the request. Defaults to {} . |
Return value: Returns a Promise
that resolves to a Models.EmbeddingsTaskStatus
instance.
Note:
You can also use the [
waitForDone
] method of theModels.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:
async retrieve(id: string, options: RequestOptions = {}): Promise<Models.EmbeddingsTask>
const response = await client.embed.task.retrieve('<YOUR_TASK_ID>')
console.log(`Task ID: ${response.id}`);
console.log(`Engine Name: ${response.engineName}`);
console.log(`Status: ${response.status}`);
if (response.videoEmbeddings && response.videoEmbeddings.length > 0) {
response.videoEmbeddings.forEach((embedding, i) => {
console.log(`\nEmbedding ${i + 1}:`);
console.log(` Start Offset: ${embedding.startOffsetSec} seconds`);
console.log(` End Offset: ${embedding.endOffsetSec} seconds`);
console.log(` Embedding Scope: ${embedding.embeddingScope}`);
console.log(` Embedding Values: ${embedding.embedding.float.slice(0, 5)} (truncated)`);
});
} else {
console.log("No video embeddings available");
}
Parameters:
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the video embedding task. |
options | RequestOptions | No | Additional options for the request. Defaults to {} . |
Return value: Returns a Promise
that resolves to a Models.EmbeddingsTask
instance.
API Reference: For a description of each field in the response, see the Retrieve video embeddings page.
Related guide: Create video embeddings.