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:

1 def create(
2     self,
3     model_name: str,
4     *,
5     video_file: Union[str, BinaryIO, None] = None,
6     video_url: Optional[str] = None,
7     video_start_offset_sec: Optional[float] = None,
8     video_end_offset_sec: Optional[float] = None,
9     video_clip_length: Optional[int] = None,
10     video_embedding_scopes: Optional[List[Literal["clip", "video"]]] = None,
11     **kwargs
12 ) -> models.EmbeddingsTask

Parameters:

Name	Type	Required	Description
`model_name`	`Literal["Marengo-retrieval-2.7"]`	Yes	The name of the video understanding model to use. Example: “Marengo-retrieval-2.7”.
`video_file`	`Union[str, BinaryIO, None]`	No	Path to the video file or a file-like object.
`video_url`	`Optional[str]`	No	The publicly accessible URL of the video.
`video_start_offset_sec`	`Optional[float]`	No	The start offset in seconds from the beginning of the video where processing should begin.
`video_end_offset_sec`	`Optional[float]`	No	The end offset in seconds from the beginning of the video where processing should stop.
`video_clip_length`	`Optional[int]`	No	The desired duration in seconds for each clip for which the platform generates an embedding.
`video_embedding_scopes`	`Optional[List[Literal["clip", "video"]]]`	No	Specifies the embedding scope. Valid values are: - `["clip"]` - `["clip", "video"]`
`**kwargs`	`dict`	No	Additional keyword arguments for the request.

Return value: Returns a models.EmbeddingsTask object representing the new video embedding task.

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:

1 def status(self, task_id: str, **kwargs) -> models.EmbeddingsTaskStatus

Parameters:

Name	Type	Required	Description
`task_id`	`string`	Yes	The unique identifier of the video embedding task.
`**kwargs`	`dict`	No	Additional keyword arguments for the request.

Return value: Returns a models.EmbeddingsTaskStatus object containing the current status of the embedding task.

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.

1 def wait_for_done(
2     self,
3     *,
4     sleep_interval: float = 5.0,
5     callback: Optional[Callable[[EmbeddingsTask], None]] = None,
6     **kwargs,
7 ) -> str

Parameters

Name	Type	Required	Description
`sleep_interval`	`float`	No	Sets the time in seconds to wait between status checks. Must be greater than 0. Default is 5.0.
`callback`	`Optional[Callable[[EmbeddingsTask], None]]`	No	Provides an optional function to call after each status check. The function receives the current task object. Use this to monitor progress.
`**kwargs`	`dict`	No	Passes additional keyword arguments to the `update_status` method when checking the task status.

Return value: Returns a string representing the status of the task.

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:

1 def retrieve(self, **kwargs) -> EmbeddingsTask

Parameters:

Name	Type	Required	Description
`**kwargs`	`dict`	No	Additional keyword arguments for the request.

Return value: Returns a models.EmbeddingsTask object containing the details of the embedding task, including the embeddings if available. The video_embeddings property of the returned object is a RootModelList of VideoEmbedding objects when the task is completed, or None if the embeddings are not yet available.

API Reference: For a description of each field in the request and 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 creating video embeddings.

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