The IndexesClient.VideosClient class provides methods to manage the videos you’ve uploaded to the platform.

Methods

Retrieve video information

Description: This method retrieves information about the specified video.

Function signature and example:

1 def retrieve(
2     self,
3     index_id: str,
4     video_id: str,
5     *,
6     embedding_option: Optional[Union[VideosRetrieveRequestEmbeddingOptionItem, Sequence[VideosRetrieveRequestEmbeddingOptionItem]]] = None,
7     transcription: Optional[bool] = None,
8     request_options: Optional[RequestOptions] = None,
9 ) -> VideosRetrieveResponse

Parameters:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index to which the video has been uploaded.
`video_id`	`str`	Yes	The unique identifier of the video to retrieve.
`embedding_option`	`Union` `[VideosRetrieveRequestEmbeddingOptionItem, Sequence` `[VideosRetrieveRequestEmbeddingOptionItem]]`	No	Specifies which types of embeddings to retrieve. You can include one or more of the following values: - `visual-text`: Returns visual embeddings optimized for text search. - `audio`: Returns audio embeddings. To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model version 2.7 or later. The platform does not return embeddings if you don’t provide this parameter. The values you specify must be included in the `model_options` defined when the index was created.
`transcription`	`bool`	No	Indicates whether to retrieve a transcription of the spoken words for the indexed video.
`request_options`	`RequestOptions`	No	Request-specific configuration.

Return value: Returns a VideosRetrieveResponse object representing the retrieved video.

The VideosRetrieveResponse class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of the video.
`created_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the video indexing task was created.
`updated_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the corresponding video indexing task was last updated.
`indexed_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the video indexing task has been completed.
`system_metadata`	`Optional[VideosRetrieveResponseSystemMetadata]`	System-generated metadata about the video.
`user_metadata`	`Optional[Dict[str, Optional[Any]]]`	User-generated metadata about the video.
`hls`	`Optional[HlsObject]`	HLS streaming information for the video.
`embedding`	`Optional[VideosRetrieveResponseEmbedding]`	Contains the embedding and the associated information. Returned when the `embedding_option` parameter is specified in the request.
`transcription`	`Optional[TranscriptionData]`	A list of transcription segments with spoken words and their timestamps.

The VideosRetrieveResponseSystemMetadata class contains the following properties:

Name	Type	Description
`duration`	`Optional[float]`	The duration of the video.
`filename`	`Optional[str]`	The filename of the video.
`fps`	`Optional[float]`	The frames per second of the video.
`height`	`Optional[int]`	The height of the video.
`width`	`Optional[int]`	The width of the video.

The VideosRetrieveResponseEmbedding class contains the following properties:

Name	Type	Description
`model_name`	`Optional[str]`	The name of the video understanding model used to create the embedding.
`video_embedding`	`Optional[VideosRetrieveResponseEmbeddingVideoEmbedding]`	An object that contains the embeddings.

The VideosRetrieveResponseEmbeddingVideoEmbedding class contains the following properties:

Name	Type	Description
`segments`	`Optional[List[VideoSegment]]`	An array of objects that contains the embeddings for each individual segment.

The TranscriptionDataItem class contains the following properties:

Name	Type	Description
`start`	`Optional[float]`	The start of the time range, expressed in seconds.
`end`	`Optional[float]`	The end of the time range, expressed in seconds.
`value`	`Optional[str]`	Text representing the spoken words within this time range.

API Reference: Retrieve video information.

Description: This method returns a list of the videos in the specified index. By default, the platform returns your videos sorted by creation date, with the newest at the top of the list.

Function signature and example:

1 def list(
2     self,
3     index_id: str,
4     *,
5     page: Optional[int] = None,
6     page_limit: Optional[int] = None,
7     sort_by: Optional[str] = None,
8     sort_option: Optional[str] = None,
9     filename: Optional[str] = None,
10     duration: Optional[float] = None,
11     fps: Optional[float] = None,
12     width: Optional[float] = None,
13     height: Optional[int] = None,
14     size: Optional[float] = None,
15     created_at: Optional[str] = None,
16     updated_at: Optional[str] = None,
17     user_metadata: Optional[Dict[str, Optional[VideosListRequestUserMetadataValue]]] = None,
18     request_options: Optional[RequestOptions] = None,
19 ) -> SyncPager[VideoVector]

Parameters:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index for which the API will retrieve the videos.
`page`	`int`	No	A number that identifies the page to retrieve. Default: `1`.
`page_limit`	`int`	No	The number of items to return on each page. Default: `10`. Max: `50`.
`sort_by`	`str`	No	The field to sort on. Available options: `updated_at`, `created_at`. Default: `created_at`.
`sort_option`	`str`	No	The sorting direction. Available options: `asc`, `desc`. Default: `desc`.
`filename`	`str`	No	Filter by filename.
`duration`	`float`	No	Filter by duration. Expressed in seconds.
`fps`	`float`	No	Filter by frames per second.
`width`	`float`	No	Filter by width.
`height`	`int`	No	Filter by height.
`size`	`float`	No	Filter by size. Expressed in bytes.
`created_at`	`str`	No	Filter videos by the creation date and time of their associated indexing tasks, in the RFC 3339 format.
`updated_at`	`str`	No	Filter videos by the last update date and time, in the RFC 3339 format. Applies only to videos updated using the PUT method.
`user_metadata`	`Dict` `[str, Optional` `[VideosListRequestUserMetadataValue]]`	No	Filter by user-defined metadata. You must first add user-defined metadata to your video.
`request_options`	`RequestOptions`	No	Request-specific configuration.

Return value: Returns a SyncPager[VideoVector] object that allows you to iterate through the paginated list of videos in the specified index.

The SyncPager[T] class contains the following properties and methods:

Name	Type	Description
`items`	`Optional[List[T]]`	A list containing the current page of items. Can be `None`.
`has_next`	`bool`	Indicates whether there is a next page to load.
`get_next`	`Optional[Callable[[], Optional[SyncPager[T]]]]`	A callable function that retrieves the next page. Can be `None`.
`response`	`Optional[BaseHttpResponse]`	The HTTP response object. Can be `None`.
`next_page()`	`Optional[SyncPager[T]]`	Calls `get_next()` if available and returns the next page object.
`__iter__()`	`Iterator[T]`	Allows iteration through all items across all pages using `for` loops.
`iter_pages()`	`Iterator[SyncPager[T]]`	Allows iteration through page objects themselves.

The VideoVector class contains the following properties:

Name	Type	Description
`id`	`Optional[str]`	The unique identifier of a video. The platform creates a new video object and assigns it a unique identifier when the video has successfully been indexed.
`created_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the video indexing task was created.
`updated_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the video indexing task object was last updated.
`indexed_at`	`Optional[str]`	The date and time, in the RFC 3339 format, that the video indexing task has been completed.
`system_metadata`	`Optional[VideoVectorSystemMetadata]`	System-generated metadata about the video.

The VideoVectorSystemMetadata class contains the following properties:

Name	Type	Description
`filename`	`Optional[str]`	The filename of the video.
`duration`	`Optional[float]`	The duration of the video.
`fps`	`Optional[float]`	The frames per second of the video.
`width`	`Optional[int]`	The width of the video.
`height`	`Optional[int]`	The height of the video.
`size`	`Optional[float]`	The size of the video in bytes.

API Reference: List videos page.

Update video information

Description: This method updates the title and metadata of a video.

Function signature and example:

1 def update(
2     self,
3     index_id: str,
4     video_id: str,
5     *,
6     user_metadata: Optional[Dict[str, Optional[Any]]] = OMIT,
7     request_options: Optional[RequestOptions] = None,
8 ) -> None

Parameters:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index to which the video has been uploaded.
`video_id`	`str`	Yes	The unique identifier of the video to update.
`user_metadata`	`Optional[Dict[str, Optional[Any]]]`	No	Metadata that helps you categorize your videos. You can specify a list of keys and values. Keys must be of type `string`, and values can be of the following types: `string`, `integer`, `float` or `boolean`. If you want to store other types of data such as objects or arrays, you must convert your data into string values. You cannot override system-generated metadata fields: `duration`, `filename`, `fps`, `height`, `model_names`, `size`, `video_title`, `width`.
`request_options`	`RequestOptions`	No	Request-specific configuration.

Return value: None. The method doesn’t return any value.

API Reference: Update video information.

Delete video information

Description: This method deletes all the information about the specified video. This action cannot be undone.

Function signature and example:

1 def delete(
2     self,
3     index_id: str,
4     video_id: str,
5     *,
6     request_options: Optional[RequestOptions] = None
7 ) -> None

Parameters:

Name	Type	Required	Description
`index_id`	`str`	Yes	The unique identifier of the index to which the video has been uploaded.
`video_id`	`str`	Yes	The unique identifier of the video to delete.
`request_options`	`RequestOptions`	No	Request-specific configuration.

Return value: None. The method doesn’t return any value.

API Reference: Delete video information.