The EmbedClient.TasksClient 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 that uploads a video to the platform.

Your video files must meet the format requirements.

Function signature and example:

1 def create(
2     self,
3     *,
4     model_name: str,
5     video_file: typing.Optional[core.File] = OMIT,
6     video_url: typing.Optional[str] = OMIT,
7     video_start_offset_sec: typing.Optional[float] = OMIT,
8     video_end_offset_sec: typing.Optional[float] = OMIT,
9     video_clip_length: typing.Optional[float] = OMIT,
10     video_embedding_scope: typing.Optional[typing.List[TasksCreateRequestVideoEmbeddingScopeItem]] = OMIT,
11     request_options: typing.Optional[RequestOptions] = None,
12 ) -> TasksCreateResponse

Parameters:

Name	Type	Required	Description
`model_name`	`str`	Yes	The name of the model you want to use. The following models are available: - `marengo3.0`: Enhanced model with sports intelligence and extended content support. For a list of the new features, see the New in Marengo 3.0 section. - `marengo2.7`: Video embedding model for multimodal search.
`video_file`	`typing.Optional[core.File]`	No	The video file to upload.
`video_url`	`typing.Optional[str]`	No	Specify this parameter to upload a video from a publicly accessible URL.
`video_start_offset_sec`	`typing.Optional[float]`	No	The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video. Default: 0, Min: 0, Max: Duration of the video minus `video_clip_length`.
`video_end_offset_sec`	`typing.Optional[float]`	No	The end offset in seconds from the beginning of the video where processing should stop. You must set both start and end offsets when using this parameter. Min: video_start_offset + video_clip_length, Max: Duration of the video file.
`video_clip_length`	`typing.Optional[float]`	No	The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets. Default: 6, Min: 2, Max: 10.
`video_embedding_scope`	`typing.` `Optional` `[typing.List` `[TasksCreateRequestVideoEmbeddingScopeItem]]`	No	Defines the scope of video embedding generation. Valid values are: `["clip"]` and `["clip", "video"]`. Default: `clip`.
`request_options`	`typing.Optional[RequestOptions]`	No	Request-specific configuration.

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

The TasksCreateResponse class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the video embedding task. You can use the identifier to retrieve the status of your task or retrieve the embedding.

API Reference: Create a video embedding task.

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, *, request_options: typing.Optional[RequestOptions] = None) -> TasksStatusResponse

Parameters:

Name	Type	Required	Description
`task_id`	`string`	Yes	The unique identifier of the video embedding task.
`request_options`	`typing.Optional[RequestOptions]`	No	Request-specific configuration.

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

The TasksStatusResponse class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the video embedding task.
`status`	`Optional[str]`	The status of the video indexing task. It can take one of the following values: `processing`, `ready` or `failed`.
`model_name`	`Optional[str]`	The name of the video understanding model the platform used to create the embedding.
`video_embedding`	`Optional[TasksStatusResponseVideoEmbedding]`	An object containing the metadata associated with the embedding.

The TasksStatusResponseVideoEmbedding class contains the following properties:

Name	Type	Description
`metadata`	`Optional[VideoEmbeddingMetadata]`	Metadata associated with the embedding.

The VideoEmbeddingMetadata class extends BaseEmbeddingMetadata and contains the following properties:

Name	Type	Description
`video_clip_length`	`Optional[float]`	The duration for each clip in seconds, as specified by the `video_clip_length` parameter. Note that the platform automatically truncates video segments shorter than 2 seconds.
`video_embedding_scope`	`Optional[List[str]]`	The scope you’ve specified in the request. It can take one of the following values: `['clip']` or `['clip', 'video']`.
`duration`	`Optional[float]`	The total duration of the video in seconds.
`input_url`	`Optional[str]`	The URL of the media file used to generate the embedding. Present if a URL was provided in the request.
`input_filename`	`Optional[str]`	The name of the media file used to generate the embedding. Present if a file was provided in the request.

API Reference: Retrieve the status of a video embedding task.

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     task_id: str,
4     *,
5     sleep_interval: float = 5.0,
6     callback: typing.Optional[typing.Callable[[TasksStatusResponse], None]] = None,
7     request_options: typing.Optional[RequestOptions] = None,
8 ) -> TasksStatusResponse

Parameters

Name	Type	Required	Description
`task_id`	`str`	Yes	The unique identifier of the task to wait for.
`sleep_interval`	`float`	No	Sets the time in seconds to wait between status checks. Must be greater than 0. Default: 5.0.
`callback`	`Optional[Callable[[TasksStatusResponse], None]]`	No	Provides an optional function to call after each status check. The function receives the current task response. Use this to monitor progress.
`request_options`	`Optional[RequestOptions]`	No	Request-specific configuration.

Return value: Returns a TasksStatusResponse object containing the status of your completed task. See the Retrieve the status of a video embedding task section above for complete property details.

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(
2     self,
3     task_id: str,
4     *,
5     embedding_option: typing.Optional[
6         typing.Union[
7             TasksRetrieveRequestEmbeddingOptionItem, typing.Sequence[TasksRetrieveRequestEmbeddingOptionItem]
8         ]
9     ] = None,
10     request_options: typing.Optional[RequestOptions] = None,
11 ) -> TasksRetrieveResponse

Parameters:

Name	Type	Required	Description
`task_id`	`str`	Yes	The unique identifier of your video embedding task.
`embedding_option`	`typing.` `Optional` `[typing.Union` `[TasksRetrieveRequestEmbeddingOptionItem, typing.` `Sequence` `[TasksRetrieveRequestEmbeddingOptionItem]]]`	No	Specifies which types of embeddings to retrieve. Values vary depending on the version of the model. For details, see the Embedding options section. The platform returns all available embeddings if you don’t provide this parameter.
`request_options`	`typing.Optional[RequestOptions]`	No	Request-specific configuration.

Return value: Returns a TasksRetrieveResponse object containing your embeddings.

The TasksRetrieveResponse class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the video embedding task.
`model_name`	`Optional[str]`	The name of the video understanding model the platform used to create the embedding.
`status`	`Optional[str]`	The status of the video indexing task. It can take one of the following values: `processing`, `ready` or `failed`.
`created_at`	`Optional[datetime]`	The date and time, in the RFC 3339 format, that the video embedding task was created.
`video_embedding`	`Optional[TasksRetrieveResponseVideoEmbedding]`	An object containing the embeddings and metadata.

The TasksRetrieveResponseVideoEmbedding class contains the following properties:

Name	Type	Description
`metadata`	`Optional[VideoEmbeddingMetadata]`	Metadata associated with the embedding.
`segments`	`Optional[List[VideoSegment]]`	An array of objects containing the embeddings for each video segment and the associated information.

The VideoEmbeddingMetadata class extends BaseEmbeddingMetadata and contains the following properties:

Name	Type	Description
`video_clip_length`	`Optional[float]`	The duration for each clip in seconds. Note that the platform automatically truncates video segments shorter than 2 seconds.
`video_embedding_scope`	`Optional[List[str]]`	The scope you’ve specified in the request. It can take one of the following values: `['clip']` or `['clip', 'video']`.
`duration`	`Optional[float]`	The total duration of the video in seconds.
`input_url`	`Optional[str]`	The URL of the media file used to generate the embedding. Present if a URL was provided in the request.
`input_filename`	`Optional[str]`	The name of the media file used to generate the embedding. Present if a file was provided in the request.

The VideoSegment class extends AudioSegment and contains the following properties:

Name	Type	Description
`start_offset_sec`	`Optional[float]`	The start time, in seconds, from which the platform generated the embedding.
`end_offset_sec`	`Optional[float]`	The end time, in seconds, of the video segment for this embedding.
`embedding_option`	`Optional[str]`	The type of the embedding.
`embedding_scope`	`Optional[str]`	The scope of the video embedding.
`float_`	`Optional[List[float]]`	An array of floating point numbers representing the embedding. You can use this array with cosine similarity for various downstream tasks.

API Reference: Retrieve video embeddings.

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