Manage videos
The [`resources.Video`](https://github.com/twelvelabs-io/twelvelabs-python/blob/main/twelvelabs/resources/video.py) 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**:
<CodeBlock>
```python Function signature
def retrieve(
self,
index_id: str,
id: str,
*,
embed: Optional[bool] = None,
**kwargs,
) -> models.Video
```
```python Python example
def print_segments(segments: List[SegmentEmbedding], max_elements: int = 5):
for segment in segments:
print(
f" embedding_scope={segment.embedding_scope} start_offset_sec={segment.start_offset_sec} end_offset_sec={segment.end_offset_sec}"
)
print(f" embeddings: {segment.embeddings_float[:max_elements]}")
video = client.index.video.retrieve(index_id="<YOUR_INDEX_ID>", id="<YOUR_VIDEO_ID>", embed=True)
print(f"ID: {video.id}")
print(f"Created at: {video.created_at}")
print(f"Updated at: {video.updated_at}")
print(f"Indexed at: {video.indexed_at}")
print("Metadata:")
print(f" Filename: {video.metadata.filename}")
print(f" Duration: {video.metadata.duration}")
print(f" FPS: {video.metadata.fps}")
print(f" Width: {video.metadata.width}")
print(f" Height: {video.metadata.height}")
print(f" Size: {video.metadata.size}")
if video.hls:
print("HLS:")
print(f" Video URL: {video.hls.video_url}")
print(" Thumbnail URLs:")
for url in video.hls.thumbnail_urls or []:
print(f" {url}")
print(f" Status: {video.hls.status}")
print(f" Updated At: {video.hls.updated_at}")
if video.source:
print("Source:")
print(f" Type: {video.source.type}")
print(f" Name: {video.source.name}")
print(f" URL: {video.source.url}")
if video.embedding:
print(f"Engine_name={video.embedding.engine_name}")
print("Embeddings:")
print_segments(video.embedding.video_embedding.segments)
```
</CodeBlock>
**Parameters**:
| Name | Type | Required | Description |
| :--------- | :----- | :------- | :----------------------------------------------------------------------------- |
| `**kwargs` | `dict` | No | Additional keyword arguments for the request. |
| `index_id` | `str` | Yes | The unique identifier of the index to which the video has been uploaded. |
| `id` | `str` | Yes | The unique identifier of the video to retrieve. |
| `embed` | `bool` | No | Set this parameter to `True` to retrieve the video embedding in the response. |
**Return value**: Returns a [`models.Video`](https://github.com/twelvelabs-io/twelvelabs-python/blob/main/twelvelabs/models/video.py) object representing the retrieved video.
**API Reference**: For a description of each field in the request and response, see the [Retrieve video information](/v1.2/api-reference/videos/retrieve) 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**:
<CodeBlock>
```python Function signature
def list(
self,
index_id: str,
*,
id: Optional[str] = None,
filename: Optional[str] = None,
size: Optional[Union[int, Dict[str, int]]] = None,
width: Optional[Union[int, Dict[str, int]]] = None,
height: Optional[Union[int, Dict[str, int]]] = None,
duration: Optional[Union[int, Dict[str, int]]] = None,
fps: Optional[Union[int, Dict[str, int]]] = None,
metadata: Optional[Dict[str, Any]] = None,
created_at: Optional[Union[str, Dict[str, str]]] = None,
updated_at: Optional[Union[str, Dict[str, str]]] = None,
page: Optional[int] = None,
page_limit: Optional[int] = None,
sort_by: Optional[str] = None,
sort_option: Optional[str] = None,
**kwargs
) -> RootModelList[models.Video]
```
```python Python example
videos = client.index.video.list(
index_id="<YOUR_INDEX_ID>",
id="<YOUR_VIDEO_ID>",
filename="<YOUR_FILENAME>",
size=1024,
width=920,
height=1080,
duration=100,
fps=30,
metadata={"category": "nature"},
created_at="2024-09-17T07:53:46.365Z",
updated_at="2024-09-17T07:53:46.365Z",
page=1,
page_limit=5,
sort_by="created_at",
sort_option="desc"
)
for video in videos:
print(f"ID: {video.id}")
print(f" Created at: {video.created_at}")
print(f" Updated at: {video.updated_at}")
print(" Metadata:")
print(f" Filename: {video.metadata.filename}")
print(f" Duration: {video.metadata.duration}")
print(f" FPS: {video.metadata.fps}")
print(f" Width: {video.metadata.width}")
print(f" Height: {video.metadata.height}")
print(f" Size: {video.metadata.size}")
if video.hls:
print(" HLS:")
print(f" Video URL: {video.hls.video_url}")
print(" Thumbnail URLs:")
for url in video.hls.thumbnail_urls or []:
print(f" {url}")
print(f" Status: {video.hls.status}")
print(f" Updated At: {video.hls.updated_at}")
if video.source:
print(" Source:")
print(f" Type: {video.source.type}")
print(f" Name: {video.source.name}")
print(f" URL: {video.source.url}")
```
</CodeBlock>
**Parameters**:
| Name | Type | Required | Description |
| ------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `index_id` | `str` | Yes | The unique identifier of the index for which the API will retrieve the videos. |
| `id` | `Optional[str]` | No | Filter by the unique identifier of a video. |
| `filename` | `Optional[str]` | No | Filter by the name of the video file. |
| `size` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the size of the video file. This parameter can be an integer or a dictionary for range queries. |
| `width` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the width of the video. This parameter can be an integer or a dictionary for range queries. |
| `height` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the height of the video. This parameter can be an integer or a dictionary for range queries. |
| `duration` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the duration of the video. This parameter can be an integer or a dictionary for range queries. |
| `fps` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the number frames per second. This parameter can be an integer or a dictionary for range queries. |
| `metadata` | `Optional[Dict[str, Any]]` | No | Filter by metadata. |
| `created_at` | `Optional[Union[str, Dict[str, str]]]` | No | Filter by the creation date. This parameter can be a string or a dictionary for range queries. |
| `updated_at` | `Optional[Union[str, Dict[str, str]]]` | No | Filter by the last update date. This parameter can be a string or a dictionary for range queries. |
| `page` | `Optional[int]` | No | Page number for pagination. |
| `page_limit` | `Optional[int]` | No | Number of items per page. |
| `sort_by` | `Optional[str]` | No | Field to sort by. |
| `sort_option` | `Optional[str]` | No | Sort order. You can specify one of the following values: "asc" or "desc". |
| `**kwargs` | `dict` | No | Additional keyword arguments for the request. |
**Return value**: Returns a [`RootModelList`](https://github.com/twelvelabs-io/twelvelabs-python/blob/main/twelvelabs/models/_base.py) containing [`models.Video`](https://github.com/twelvelabs-io/twelvelabs-python/blob/main/twelvelabs/models/video.py) 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](/v1.2/api-reference/videos/list) page.
**Related guides**:
- [Direct pagination](/v1.2/docs/guides/pagination/indexes-videos-and-tasks#direct-pagination).
- [Sorting > Indexes, videos, and tasks](/v1.2/docs/guides/sorting/indexes-videos-and-tasks).
- [Filtering > Indexes, videos, and tasks](/v1.2/docs/guides/filtering/indexes-videos-and-tasks).
## 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**:
<CodeBlock>
```python Function signature
def list_pagination(
self,
index_id: str,
*,
id: Optional[str] = None,
filename: Optional[str] = None,
size: Optional[Union[int, Dict[str, int]]] = None,
width: Optional[Union[int, Dict[str, int]]] = None,
height: Optional[Union[int, Dict[str, int]]] = None,
duration: Optional[Union[int, Dict[str, int]]] = None,
fps: Optional[Union[int, Dict[str, int]]] = None,
metadata: Optional[Dict[str, Any]] = None,
created_at: Optional[Union[str, Dict[str, str]]] = None,
updated_at: Optional[Union[str, Dict[str, str]]] = None,
page: Optional[int] = None,
page_limit: Optional[int] = None,
sort_by: Optional[str] = None,
sort_option: Optional[str] = None,
**kwargs
) -> models.VideoListWithPagination
```
```python Python example
def print_page(page):
for video in page:
print(f"ID: {video.id}")
print(f" Created at: {video.created_at}")
print(f" Updated at: {video.updated_at}")
print(" Metadata:")
print(f" Filename: {video.metadata.filename}")
print(f" Duration: {video.metadata.duration}")
print(f" FPS: {video.metadata.fps}")
print(f" Width: {video.metadata.width}")
print(f" Height: {video.metadata.height}")
print(f" Size: {video.metadata.size}")
if video.hls:
print(" HLS:")
print(f" Video URL: {video.hls.video_url}")
print(" Thumbnail URLs:")
for url in video.hls.thumbnail_urls or []:
print(f" {url}")
print(f" Status: {video.hls.status}")
print(f" Updated At: {video.hls.updated_at}")
if video.source:
print(" Source:")
print(f" Type: {video.source.type}")
print(f" Name: {video.source.name}")
print(f" URL: {video.source.url}")
# Fetch the initial page of results
video_paginator = client.index.video.list_pagination(
index_id="<YOUR_INDEX_ID>",
id="<YOUR_VIDEO_ID",
filename="01.mp4",
size=1024,
width=920,
height=1080,
duration=100,
fps=30,
metadata={"category": "nature"},
created_at="2024-09-17T07:53:46.365Z",
updated_at="2024-09-17T07:53:46.365Z",
page=1,
page_limit=5,
sort_by="created_at",
sort_option="desc"
)
# Print the first page of results
print_page(video_paginator.data)
# Iterate through subsequent pages
while True:
try:
next_task_page = next(video_paginator)
print_page(next_task_page)
except StopIteration:
break
```
</CodeBlock>
**Parameters**:
| Name | Type | Required | Description |
| ------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `index_id` | `str` | Yes | The unique identifier of the index for which the API will retrieve the videos. |
| `id` | `Optional[str]` | No | Filter by the unique identifier of a video. |
| `filename` | `Optional[str]` | No | Filter by the name of the video file. |
| `size` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the size of the video file. This parameter can be an integer or a dictionary for range queries. |
| `width` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the width of the video. This parameter can be an integer or a dictionary for range queries. |
| `height` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the height of the video. This parameter can be an integer or a dictionary for range queries. |
| `duration` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the duration of the video. This parameter can be an integer or a dictionary for range queries. |
| `fps` | `Optional[Union[int, Dict[str, int]]]` | No | Filter by the number of frames per second. This parameter can be an integer or a dictionary for range queries. |
| `metadata` | `Optional[Dict[str, Any]]` | No | Filter by metadata. |
| `created_at` | `Optional[Union[str, Dict[str, str]]]` | No | Filter by the creation date. This parameter can be a string or a dictionary for range queries. |
| `updated_at` | `Optional[Union[str, Dict[str, str]]]` | No | Filter by the last update date. This parameter can be a string or a dictionary for range queries. |
| `page` | `Optional[int]` | No | Page number for pagination. |
| `page_limit` | `Optional[int]` | No | Number of items per page. |
| `sort_by` | `Optional[str]` | No | Field to sort by. |
| `sort_option` | `Optional[str]` | No | Sort order. You can specify one of the following values: "asc" or "desc". |
| `**kwargs` | `dict` | No | Additional keyword arguments for the request. |
**Return value**: Returns a [`models.VideoListWithPagination`](https://github.com/twelvelabs-io/twelvelabs-python/blob/main/twelvelabs/models/video.py) object, containing the list of videos that match the specified criteria and pagination information.
<Note title="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.
</Note>
**API Reference**: For a description of each field in the request and response, see the [List videos](/v1.2/api-reference/videos/list) page.
**Related guides**:
- [Iterative pagination](/v1.2/docs/guides/pagination/indexes-videos-and-tasks#iterative-pagination)
- [Sorting > Indexes, videos, and tasks](/v1.2/docs/guides/sorting/indexes-videos-and-tasks).
- [Filtering > Indexes, videos, and tasks](//v1.2/docs/guides/filtering/indexes-videos-and-tasks).
## Update video information
**Description**: This method updates the title and metadata of a video.
**Function signature and example**:
<CodeBlock>
```python Function signature
def update(
self,
index_id: str,
id: str,
*,
title: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs
) -> None
```
```python Python example
client.index.video.update(
index.id, video.id, title="<YOUR_VIDEO_TITLE>", metadata={"from_sdk": True}
)
```
</CodeBlock>
**Parameters**:
| Name | Type | Required | Description |
| :--------- | :------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `index_id` | `str` | Yes | The unique identifier of the index to which the video has been uploaded. |
| `id` | `str` | Yes | The unique identifier of the video. |
| `title` | `Optional[str]` | No | The new title for the video |
| `metadata` | `Optional[Dict[str, Any]]` | No | A dictionary containing the metadata you want to update or add. Note that only the provided properties are modified; the omitted properties remain unchanged. |
| `**kwargs` | `dict` | No | Additional 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](/v1.2/api-reference/videos/update) page.
## Delete video information
**Description**: This method deletes all the information about the specified video. This action cannot be undone.
**Function signature and example**:
<CodeBlock>
```python Function signature
def delete(self, index_id: str, id: str, **kwargs) -> None
```
```python Python example
client.task.delete(index_id="<YOUR_INDEX_ID>", id="<YOUR_VIDEO_ID>")
```
</CodeBlock>
**Parameters**:
| Name | Type | Required | Description |
| :--------- | :------- | :------- | :----------------------------------------------------------------------- |
| `index_id` | `string` | Yes | The unique identifier of the index to which the video has been uploaded. |
| `id` | `string` | Yes | The unique identifier of the video to delete. |
| `**kwargs` | `dict` | No | Additional keyword arguments for the request. |
**Return value**: `None`. The method doesn't return any value.
**API Reference**: [Delete video information](/v1.2/api-reference/videos/delete).
Built with