Python SDK

Manage videos

The resources.Video 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:

1def retrieve(
2    self,
3    index_id: str,
4    id: str,
5    *,
6    embedding_option: Optional[List[str]] = None,
7    **kwargs,
8) -> models.Video

Parameters:

NameTypeRequiredDescription
**kwargsdictNoAdditional keyword arguments for the request.
index_idstrYesThe unique identifier of the index to which the video has been uploaded.
idstrYesThe unique identifier of the video to retrieve.
embedding_optionList[str]NoSpecifies 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.

Return value: Returns a models.Video object representing the retrieved video.

API Reference: For a description of each field in the request and response, see the Retrieve video information page.

List videos with direct pagination

Description: This method returns a paginated list of the videos in the specified index based on the provided parameters. Choose this method mainly when the total number of items is manageable, or you must fetch a single page of results. By default, the platform returns your videos sorted by their upload date, with the newest at the top of the list.

Function signature and example:

1def list(
2    self,
3    index_id: str,
4    *,
5    id: Optional[str] = None,
6    filename: Optional[str] = None,
7    size: Optional[Union[int, Dict[str, int]]] = None,
8    width: Optional[Union[int, Dict[str, int]]] = None,
9    height: Optional[Union[int, Dict[str, int]]] = None,
10    duration: Optional[Union[int, Dict[str, int]]] = None,
11    fps: Optional[Union[int, Dict[str, int]]] = None,
12    user_metadata: Optional[Dict[str, Any]] = None,
13    created_at: Optional[Union[str, Dict[str, str]]] = None,
14    updated_at: Optional[Union[str, Dict[str, str]]] = None,
15    page: Optional[int] = None,
16    page_limit: Optional[int] = None,
17    sort_by: Optional[str] = None,
18    sort_option: Optional[str] = None,
19    **kwargs
20) -> RootModelList[models.Video]

Parameters:

NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index for which the API will retrieve the videos.
idOptional[str]NoFilter by the unique identifier of a video.
filenameOptional[str]NoFilter by the name of the video file.
sizeOptional[Union[int, Dict[str, int]]]NoFilter by the size of the video file. This parameter can be an integer or a dictionary for range queries.
widthOptional[Union[int, Dict[str, int]]]NoFilter by the width of the video. This parameter can be an integer or a dictionary for range queries.
heightOptional[Union[int, Dict[str, int]]]NoFilter by the height of the video. This parameter can be an integer or a dictionary for range queries.
durationOptional[Union[int, Dict[str, int]]]NoFilter by the duration of the video. This parameter can be an integer or a dictionary for range queries.
fpsOptional[Union[int, Dict[str, int]]]NoFilter by the number frames per second. This parameter can be an integer or a dictionary for range queries.
user_metadataOptional[Dict[str, Any]]NoFilter by user metadata.
created_atOptional[Union[str, Dict[str, str]]]NoFilter by the creation date. This parameter can be a string or a dictionary for range queries.
updated_atOptional[Union[str, Dict[str, str]]]NoFilter by the last update date. This parameter can be a string or a dictionary for range queries.
pageOptional[int]NoPage number for pagination.
page_limitOptional[int]NoNumber of items per page.
sort_byOptional[str]NoField to sort by.
sort_optionOptional[str]NoSort order. You can specify one of the following values: “asc” or “desc”.
**kwargsdictNoAdditional keyword arguments for the request.

Return value: Returns a RootModelList containing models.Video objects, representing the list of videos that match the specified criteria.

API Reference: For a description of each field in the request and response, see the List videos page.

Related guides:

List videos with iterative pagination

Description: This method iterates through a paginated list of the videos in the specified index based on the provided parameters. Choose this method mainly when your application must retrieve a large number of items. By default, the API returns your videos sorted by creation date, with the newest at the top of the list.

Function signature and example:

1def list_pagination(
2    self,
3    index_id: str,
4    *,
5    id: Optional[str] = None,
6    filename: Optional[str] = None,
7    size: Optional[Union[int, Dict[str, int]]] = None,
8    width: Optional[Union[int, Dict[str, int]]] = None,
9    height: Optional[Union[int, Dict[str, int]]] = None,
10    duration: Optional[Union[int, Dict[str, int]]] = None,
11    fps: Optional[Union[int, Dict[str, int]]] = None,
12    user_metadata: Optional[Dict[str, Any]] = None,
13    created_at: Optional[Union[str, Dict[str, str]]] = None,
14    updated_at: Optional[Union[str, Dict[str, str]]] = None,
15    page: Optional[int] = None,
16    page_limit: Optional[int] = None,
17    sort_by: Optional[str] = None,
18    sort_option: Optional[str] = None,
19    **kwargs
20) -> models.VideoListWithPagination

Parameters:

NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index for which the API will retrieve the videos.
idOptional[str]NoFilter by the unique identifier of a video.
filenameOptional[str]NoFilter by the name of the video file.
sizeOptional[Union[int, Dict[str, int]]]NoFilter by the size of the video file. This parameter can be an integer or a dictionary for range queries.
widthOptional[Union[int, Dict[str, int]]]NoFilter by the width of the video. This parameter can be an integer or a dictionary for range queries.
heightOptional[Union[int, Dict[str, int]]]NoFilter by the height of the video. This parameter can be an integer or a dictionary for range queries.
durationOptional[Union[int, Dict[str, int]]]NoFilter by the duration of the video. This parameter can be an integer or a dictionary for range queries.
fpsOptional[Union[int, Dict[str, int]]]NoFilter by the number of frames per second. This parameter can be an integer or a dictionary for range queries.
user_metadataOptional[Dict[str, Any]]NoFilter by user metadata.
created_atOptional[Union[str, Dict[str, str]]]NoFilter by the creation date. This parameter can be a string or a dictionary for range queries.
updated_atOptional[Union[str, Dict[str, str]]]NoFilter by the last update date. This parameter can be a string or a dictionary for range queries.
pageOptional[int]NoPage number for pagination.
page_limitOptional[int]NoNumber of items per page.
sort_byOptional[str]NoField to sort by.
sort_optionOptional[str]NoSort order. You can specify one of the following values: “asc” or “desc”.
**kwargsdictNoAdditional keyword arguments for the request.

Return value: Returns a models.VideoListWithPagination object, containing the list of videos that match the specified criteria and pagination information.

Note

To retrieve subsequent pages of results, use the iterator protocol:

  1. Call the next function, passing the VideoListWithPagination object as a parameter.
  2. Repeat this call until a StopIteration exception occurs, indicating no more pages exist.

API Reference: For a description of each field in the request and response, see the List videos page.

Related guides:

Update video information

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

Function signature and example:

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

Parameters:

NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index to which the video has been uploaded.
idstrYesThe unique identifier of the video.
user_metadataOptional[Dict[str, Any]]NoA dictionary containing the metadata you want to update or add. Note that only the provided properties are modified; the omitted properties remain unchanged.
**kwargsdictNoAdditional keyword arguments for the request.

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

API Reference: For a description of each field in the request, see the Update video information page.

Delete video information

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

Function signature and example:

1def delete(self, index_id: str, id: str, **kwargs) -> None

Parameters:

NameTypeRequiredDescription
index_idstringYesThe unique identifier of the index to which the video has been uploaded.
idstringYesThe unique identifier of the video to delete.
**kwargsdictNoAdditional keyword arguments for the request.

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

API Reference: Delete video information.