### Install TwelveLabs Python SDK

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

Installs the latest version of the twelvelabs package using pip. This is the first step to using the SDK in your Python application.

```shell
pip install twelvelabs
```

--------------------------------

### Search Client Usage Example in Python

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Demonstrates how to initialize the TwelveLabs client and perform a search operation using the client.search.create method. This requires an API key and an index ID.

```python
from twelvelabs import TwelveLabs

client = TwelveLabs(
    api_key="YOUR_API_KEY",
)
client.search.create(
    index_id="index_id",
    search_options=["visual"],
)
```

--------------------------------

### List Asynchronous Embedding Tasks with Python

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

This Python example demonstrates how to list asynchronous embedding tasks. It requires an API key and allows filtering by start and end times, status, and pagination parameters like page number and limit. The function iterates through the retrieved tasks.

```python
from twelvelabs import TwelveLabs

client = TwelveLabs(
    api_key="YOUR_API_KEY",
)
response = client.embed.v_2.tasks.list(
    started_at="2024-03-01T00:00:00Z",
    ended_at="2024-03-01T00:00:00Z",
    status="processing",
    page=1,
    page_limit=10,
)
for item in response:
    yield item

```

--------------------------------

### Example of Multiple Search Options in JSON

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Demonstrates how to specify multiple search options (visual, audio, transcription) in a JSON request body. This allows for a comprehensive search across different modalities.

```JSON
{
  "search_options": [
    "visual",
    "audio",
    "transcription"
  ]
}
```

--------------------------------

### Example of Grouping Search Results by Video in JSON

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Demonstrates how to group search results by video using the 'group_by' parameter. This organizes the output to show all clips belonging to a specific video together.

```JSON
{
  "group_by": "video"
}
```

--------------------------------

### Create a New Index with Models

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

Creates a new index for video analysis using the TwelveLabs SDK. This example demonstrates how to specify the index name and the models (Marengo and Pegasus) along with their processing options (visual, audio).

```python
from twelvelabs import TwelveLabs
from twelvelabs.indexes import IndexesCreateRequestModelsItem

try:
    index = client.indexes.create(
        index_name="<YOUR_INDEX_NAME>",
        models=[
            IndexesCreateRequestModelsItem(
                model_name="marengo3.0",
                model_options=["visual", "audio"],
            ),
            IndexesCreateRequestModelsItem(
                model_name="pegasus1.2",
                model_options=["visual", "audio"],
            ),
        ],
    )
except Exception as e:
    print(f"Error: {e}")
print(f"Created index: id={index.id} name={index.name}")
```

--------------------------------

### Example of Composed Image+Text Search in JSON

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Illustrates how to perform a composed search using both an image and text. This requires specifying the media type and providing both the media URL/file and the text query.

```JSON
{
  "query_media_type": "image",
  "query_media_url": "https://example.com/image.jpg",
  "query_text": "A cat sitting on a mat"
}
```

--------------------------------

### Search API

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

This section details how to search for relevant video content using either text or image queries. It outlines the parameters and provides code examples for both methods.

```APIDOC
## Search API

This API allows you to search for relevant video content using text or image queries.

### Search using Text Queries

Use natural language to find video segments matching specific keywords or phrases.

#### Method
POST

#### Endpoint
`/search`

#### Parameters

##### Query Parameters
- **index_id** (string) - Required - The unique identifier of your index.
- **query_text** (string) - Required - Your search query in natural language.
- **options** (array of strings) - Required - Specifies the modalities to use for the search (e.g., `["visual", "audio"]`). Must be a subset of the model options used when creating the index.

#### Request Example
```python
search_results = client.search.query(
    index_id=index.id,
    query_text="<YOUR_QUERY>",
    options=["visual", "audio"]
    )
```

#### Response

##### Success Response (200)
- **video_id** (string) - The unique identifier of the video.
- **score** (float) - Confidence score of the match.
- **start** (float) - Start time of the matching clip in seconds.
- **end** (float) - End time of the matching clip in seconds.
- **confidence** (string) - Qualitative indicator of match confidence (`high`, `medium`, `low`). Deprecated for Marengo 3.0 model.
- **rank** (integer) - Rank of the matched clip based on relevance.

##### Response Example
```json
{
  "video_id": "example_video_id",
  "score": 0.95,
  "start": 10.5,
  "end": 15.2,
  "confidence": "high",
  "rank": 1
}
```

### Search using Image Queries

Use images (local files or URLs) to find video segments semantically similar to the provided images.

#### Method
POST

#### Endpoint
`/search`

#### Parameters

##### Query Parameters
- **index_id** (string) - Required - The unique identifier of your index.
- **query_media_type** (string) - Required - Set to `"image"` for image queries.
- **query_media_file** (string) - Required if `query_media_url` is not used - Path to the local image file.
- **query_media_url** (string) - Required if `query_media_file` is not used - URL of the publicly accessible image.
- **search_options** (array of strings) - Required - Specifies the modalities to use for the search (e.g., `["visual"]`). Must be a subset of the model options used when creating the index.

#### Request Example
```python
search_results = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query_media_type="image",
    query_media_file="<YOUR_FILE_PATH>",
    search_options=["<YOUR_SEARCH_OPTIONS>"]
)
```

*Note: The response structure is similar to text queries.*
```

--------------------------------

### Use Async Client for Non-Blocking Operations in Python

Source: https://context7.com/twelvelabs-io/twelvelabs-python/llms.txt

This example demonstrates how to use the asynchronous client of the TwelveLabs Python SDK for non-blocking operations. It covers listing indexes, performing searches, and analyzing videos asynchronously within an async application context.

```python
import asyncio
from twelvelabs import AsyncTwelveLabs

async def main():
    async with AsyncTwelveLabs(api_key="YOUR_API_KEY") as client:
        # List indexes asynchronously
        indexes = await client.indexes.list()
        async for index in indexes:
            print(f"Index: {index.id}")

        # Search asynchronously
        results = await client.search.query(
            index_id="YOUR_INDEX_ID",
            query_text="interesting scene",
            search_options=["visual"],
        )
        async for clip in results:
            print(f"Found: {clip.start}s - {clip.end}s")

        # Analyze asynchronously
        result = await client.analyze(
            video_id="YOUR_VIDEO_ID",
            prompt="Summarize this video",
        )
        print(result.data)

asyncio.run(main())
```

--------------------------------

### Example of Entity Search with ID in JSON

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Shows how to use the Entity Search feature by enclosing an entity's unique identifier within '<@' and '>' markers in the text query. This targets specific entities within the video content.

```JSON
{
  "query_text": "<@entity123> is walking"
}
```

--------------------------------

### Analyze Videos (Python)

Source: https://context7.com/twelvelabs-io/twelvelabs-python/llms.txt

Demonstrates how to use the Analyze API with the TwelveLabs Python SDK to generate insights from video content. This includes creating summaries, chapters, highlights, and custom text outputs. The code snippet is a starting point for video analysis tasks.

```python
import json
from twelvelabs import TwelveLabs
from twelvelabs.types import ResponseFormat

client = TwelveLabs(api_key="YOUR_API_KEY")
video_id = "YOUR_VIDEO_ID"

```

--------------------------------

### Handle API Errors with Python SDK

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

This example demonstrates how to handle specific HTTP errors returned by the TwelveLabs API using the Python SDK's exception classes. It includes error handling for BadRequestError, NotFoundError, and a general exception catch-all.

```python
import os
from twelvelabs import TwelveLabs
from twelvelabs.errors import BadRequestError, NotFoundError

client = TwelveLabs(api_key=os.getenv("TWELVELABS_API_KEY"))
try:
    indexes = client.indexes.list()
    print(indexes)
except BadRequestError as e:
    print("Bad request.")
except NotFoundError as e:
    print("Not found.")
except Exception as e:
    print(f"An error occurred: {e}")
```

--------------------------------

### Upload Videos using Python SDK

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

This snippet demonstrates how to upload video files to a specified index using the Twelve Labs Python SDK. It iterates through video files found in a given directory, creates an indexing task for each, and waits for the task to complete. Prerequisites include having the SDK installed and valid API credentials configured. The input is a directory path containing video files and an index ID. The output is the video ID upon successful upload and indexing.

```python
from glob import glob

video_files = glob("<YOUR_VIDEO_PATH>") # Example: "/videos/*.mp4"
for video_file in video_files:
  print(f"Uploading {video_file}")
  task = client.tasks.create(index_id="<YOUR_INDEX_ID>", video_file=video_file)
  print(f"Task id={task.id}")

  task.wait_for_done(sleep_interval=5, callback=lambda t: print(f"  Status={t.status}"))
  if task.status != "ready":
      raise RuntimeError(f"Indexing failed with status {task.status}")
  print(f"Upload complete. The unique identifier of your video is {task.video_id}.")
```

--------------------------------

### Perform Open-Ended Video Analysis with Python

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

This code snippet shows how to perform open-ended analysis on a video using the TwelveLabs Python SDK. It takes a video ID and a prompt to guide the analysis and generate tailored text outputs. The prompt has a maximum length of 2,000 tokens.

```python
res = client.analyze(video_id="<YOUR_VIDEO_ID>", prompt="<YOUR_PROMPT>")
print(f"{res.data}")
```

--------------------------------

### Create a Video Index (Python)

Source: https://context7.com/twelvelabs-io/twelvelabs-python/llms.txt

Demonstrates how to create a new video index using the TwelveLabs Python SDK. It shows how to specify index name, AI models (Marengo for search, Pegasus for analysis), and addons like thumbnail generation. The code also includes listing existing indexes.

```python
from twelvelabs import TwelveLabs
from twelvelabs.indexes import IndexesCreateRequestModelsItem

client = TwelveLabs(api_key="YOUR_API_KEY")

# Create an index with both Marengo (search) and Pegasus (analysis) models
index = client.indexes.create(
    index_name="my-video-index",
    models=[
        IndexesCreateRequestModelsItem(
            model_name="marengo3.0",
            model_options=["visual", "audio"],
        ),
        IndexesCreateRequestModelsItem(
            model_name="pegasus1.2",
            model_options=["visual", "audio"],
        ),
    ],
    addons=["thumbnail"],  # Enable thumbnail generation
)
print(f"Created index: id={index.id} name={index.index_name}")

# List all indexes
for idx in client.indexes.list():
    print(f"  id={idx.id} name={idx.index_name} created_at={idx.created_at}")
```

--------------------------------

### GET /indexes/{index_id}

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves details for a specific index using its unique identifier.

```APIDOC
## GET /indexes/{index_id}

### Description
This method retrieves details about the specified index.

### Method
GET

### Endpoint
/indexes/{index_id}

### Parameters
#### Path Parameters
- **index_id** (str) - Required - Unique identifier of the index to retrieve.

#### Query Parameters
- **page** (Optional[int]) - Optional - A number that identifies the page to retrieve. Default: 1.
- **page_limit** (Optional[int]) - Optional - The number of items to return on each page. Default: 10. Max: 50.
- **sort_by** (Optional[str]) - Optional - The field to sort on. Available options: `updated_at`, `created_at`. Default: `created_at`.
- **sort_option** (Optional[str]) - Optional - The sorting direction. Available options: `asc`, `desc`. Default: `desc`.
- **index_name** (Optional[str]) - Optional - Filter by the name of an index.
- **model_options** (Optional[str]) - Optional - Filter by the model options. Comma-separated if multiple.
- **model_family** (Optional[str]) - Optional - Filter by the model family. Available values: `marengo`, `pegasus`. Single value only.
- **created_at** (Optional[str]) - Optional - Filter indexes by creation date and time (RFC 3339 format). Returns indexes created on or after the specified time.
- **updated_at** (Optional[str]) - Optional - Filter indexes by last update date and time (RFC 3339 format). Returns indexes updated on or after the specified time.

#### Request Body
None

### Request Example
```python
{
  "index_id": "6298d673f1090f1100476d4c"
}
```

### Response
#### Success Response (200)
- **message** (str) - Success message.
- **index** (object) - Details of the index.
  - **id** (str) - The unique identifier of the index.
  - **name** (str) - The name of the index.
  - **status** (str) - The status of the index.
  - **created_at** (str) - The timestamp when the index was created.
  - **updated_at** (str) - The timestamp when the index was last updated.
  - **models** (Array) - Details about the models used for the index.
  - **addons** (Array) - Details about the enabled addons.

#### Response Example
```json
{
  "message": "Index retrieved successfully.",
  "index": {
    "id": "6298d673f1090f1100476d4c",
    "name": "myIndex",
    "status": "active",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:05:00Z",
    "models": [
      {
        "name": "marengo3.0",
        "options": ["visual", "audio"]
      }
    ],
    "addons": ["thumbnail"]
  }
}
```
```

--------------------------------

### Initialize TwelveLabs Python SDK Client

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

Imports the TwelveLabs SDK and instantiates the client with your API key. Ensure you replace '<YOUR_API_KEY>' with your actual Twelve Labs API key.

```python
from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")
```

--------------------------------

### Initialize TwelveLabs Client (Python)

Source: https://context7.com/twelvelabs-io/twelvelabs-python/llms.txt

Initializes the TwelveLabs client using an API key, which can be loaded from environment variables. It demonstrates both direct initialization and usage as a context manager for automatic resource cleanup. This client is essential for accessing all platform features.

```python
import os
from twelvelabs import TwelveLabs

# Initialize the client
client = TwelveLabs(api_key=os.getenv("TWELVELABS_API_KEY"))

# Or use as context manager for automatic cleanup
with TwelveLabs(api_key=os.getenv("TWELVELABS_API_KEY")) as client:
    indexes = client.indexes.list()
    for index in indexes:
        print(f"Index: {index.id} - {index.index_name}")
```

--------------------------------

### Task Transfers API - Get Logs

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves logs for task transfers. Requires an integration ID.

```APIDOC
## GET /tasks/transfers/logs

### Description
Retrieves logs associated with task transfers. This endpoint requires the `integration_id` to specify which integration's logs to fetch.

### Method
GET

### Endpoint
/tasks/transfers/logs

### Parameters
#### Query Parameters
- **integration_id** (str) - Required - The unique identifier for the integration.
- **request_options** (RequestOptions) - Optional - Request-specific configuration, such as timeouts or retries.

### Request Example
```python
from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="YOUR_API_KEY")
logs = client.tasks.transfers.get_logs(integration_id="your_integration_id")
print(logs)
```

### Response
#### Success Response (200)
- **logs** (list) - A list of log entries related to task transfers.
- **next_page_token** (str) - Token for paginating to the next set of results, if available.

#### Response Example
```json
{
  "logs": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "level": "INFO",
      "message": "Task transfer initiated."
    },
    {
      "timestamp": "2023-10-27T10:05:00Z",
      "level": "SUCCESS",
      "message": "Task transfer completed successfully."
    }
  ],
  "next_page_token": "some_token_if_more_pages_exist"
}
```
```

--------------------------------

### GET /entity_collections/{entity_collection_id}/entities/{entity_id}

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves details about a specific entity within an entity collection.

```APIDOC
## GET /entity_collections/{entity_collection_id}/entities/{entity_id}

### Description
This method retrieves details about the specified entity.

### Method
GET

### Endpoint
/entity_collections/{entity_collection_id}/entities/{entity_id}

### Parameters
#### Path Parameters
- **entity_collection_id** (str) - Required - The unique identifier of the entity collection.
- **entity_id** (str) - Required - The unique identifier of the entity to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The unique identifier of the entity.
- **name** (str) - The name of the entity.
- **description** (str) - The description of the entity.
- **metadata** (object) - The metadata associated with the entity.
- **created_at** (str) - The timestamp when the entity was created.
- **updated_at** (str) - The timestamp when the entity was last updated.
- **asset_ids** (array[str]) - The list of asset IDs associated with the entity.
- **entity_collection_id** (str) - The ID of the entity collection the entity belongs to.

#### Response Example
```json
{
  "id": "entity_id_1",
  "name": "My entity",
  "description": "Optional description",
  "metadata": {
    "sport": "soccer",
    "teamId": 42,
    "performanceScore": 8.7,
    "isActive": true
  },
  "created_at": "2023-10-27T10:00:00Z",
  "updated_at": "2023-10-27T10:00:00Z",
  "asset_ids": ["asset_id_1", "asset_id_2"],
  "entity_collection_id": "entity_collection_id"
}
```
```

--------------------------------

### GET /embed/v2/tasks/{task_id}

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves the status and details of a specific embedding task using its task ID.

```APIDOC
## GET /embed/v2/tasks/{task_id}

### Description
Retrieves the status and details of a specific embedding task using its task ID. This endpoint is used to poll for task completion and retrieve the generated embeddings once the task status is `ready`.

### Method
GET

### Endpoint
/embed/v2/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier of the embedding task.

#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the task.
- **status** (string) - The current status of the task (`processing`, `ready`, `failed`).
- **created_at** (string) - The timestamp when the task was created.
- **updated_at** (string) - The timestamp when the task was last updated.
- **auto_create_thumbnails** (boolean) - Indicates if thumbnails were automatically created.
- **notify_url** (string) - The URL to send notifications to upon task completion.
- **metadata** (object) - User-defined metadata associated with the task.
- **source_type** (string) - The type of the source media (`audio` or `video`).
- **media_url** (string) - The URL of the source media.
- **thumbnail_url** (string) - The URL of the generated thumbnail (if applicable).
- **error_message** (string) - An error message if the task failed.
- **embeddings** (object) - Contains the generated embeddings if the status is `ready`.

#### Response Example
```json
{
  "id": "654f7a2a901234567890abcd",
  "status": "ready",
  "created_at": "2023-11-14T10:00:00Z",
  "updated_at": "2023-11-14T10:05:00Z",
  "auto_create_thumbnails": false,
  "notify_url": null,
  "metadata": {},
  "source_type": "video",
  "media_url": "https://user-bucket.com/video/long-video.mp4",
  "thumbnail_url": "https://user-bucket.com/thumbnails/long-video.jpg",
  "error_message": null,
  "embeddings": {
    "visual": [
      {
        "timestamp": 0,
        "vector": [0.1, 0.2, ...]
      }
    ],
    "audio": [
      {
        "timestamp": 0,
        "vector": [0.3, 0.4, ...]
      }
    ],
    "transcription": [
      {
        "start_timestamp": 0,
        "end_timestamp": 2,
        "text": "This is the first sentence."
      }
    ]
  }
}
```
```

--------------------------------

### Tasks Transfers Get Status API

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves the status of a data transfer task using its integration ID.

```APIDOC
## GET /tasks/transfers/status

### Description
Retrieves the status of a data transfer task using its integration ID.

### Method
GET

### Endpoint
/tasks/transfers/status

### Parameters
#### Query Parameters
- **integration_id** (str) - Required - The identifier of the integration associated with the transfer task.
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **task_id** (str) - The unique identifier for the transfer task.
- **status** (str) - The current status of the task (e.g., 'completed', 'failed', 'in_progress').
- **progress** (integer) - The completion percentage of the task.

#### Response Example
```json
{
  "message": "Task status retrieved successfully.",
  "task_id": "task-12345abcde",
  "status": "completed",
  "progress": 100
}
```
```

--------------------------------

### Create Index with Models and Addons (Python)

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Demonstrates how to create a new index using the TwelveLabs Python SDK. It specifies the index name, video understanding models with their options, and enables the thumbnail addon. Requires the 'twelvelabs' library.

```python
from twelvelabs import TwelveLabs
from twelvelabs.indexes import IndexesCreateRequestModelsItem

client = TwelveLabs(
    api_key="YOUR_API_KEY",
)
client.indexes.create(
    index_name="myIndex",
    models=[
        IndexesCreateRequestModelsItem(
            model_name="marengo3.0",
            model_options=["visual", "audio"],
        ),
        IndexesCreateRequestModelsItem(
            model_name="pegasus1.2",
            model_options=["visual", "audio"],
        ),
    ],
    addons=["thumbnail"],
)

```

--------------------------------

### GET /indexes/{index_id}/indexed_assets

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves a list of indexed assets within a specified index, sorted by creation date.

```APIDOC
## GET /indexes/{index_id}/indexed_assets

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

### Method
GET

### Endpoint
`/indexes/{index_id}/indexed_assets`

### Parameters
#### Path Parameters
- **index_id** (str) - Required - The unique identifier of the index.

#### Query Parameters
- **page** (int) - Optional - The page number for pagination. Defaults to 1.
- **page_limit** (int) - Optional - The number of items per page. Defaults to 10.
- **sort_by** (str) - Optional - The field to sort the results by. Defaults to 'created_at'.
- **sort_option** (str) - Optional - The sorting order ('asc' or 'desc'). Defaults to 'desc'.
- **filename** (str) - Optional - Filter by filename.
- **duration** (float) - Optional - Filter by duration.
- **fps** (float) - Optional - Filter by frames per second.
- **width** (float) - Optional - Filter by width.
- **height** (int) - Optional - Filter by height.
- **size** (float) - Optional - Filter by size.
- **created_at** (str) - Optional - Filter by creation timestamp (ISO 8601 format).
- **updated_at** (str) - Optional - Filter by update timestamp (ISO 8601 format).

#### Request Body
None

### Request Example
```python
from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="YOUR_API_KEY")
response = client.indexes.indexed_assets.list(
    index_id="6298d673f1090f1100476d4c",
    page=1,
    page_limit=10,
    sort_by="created_at",
    sort_option="desc",
    filename="01.mp4",
    duration=1.1,
    fps=1.1,
    width=1.1,
    height=1,
    size=1.1,
    created_at="2024-08-16T16:53:59Z",
    updated_at="2024-08-16T16:53:59Z",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page
```

### Response
#### Success Response (200)
- **indexed_assets** (list) - A list of indexed asset objects.
  - **id** (str) - The unique identifier of the indexed asset.
  - **index_id** (str) - The ID of the index this asset belongs to.
  - **filename** (str) - The name of the file.
  - **duration** (float) - The duration of the asset in seconds.
  - **fps** (float) - The frames per second of the asset.
  - **width** (float) - The width of the asset in pixels.
  - **height** (int) - The height of the asset in pixels.
  - **size** (float) - The size of the asset in bytes.
  - **created_at** (str) - The timestamp when the asset was created (ISO 8601 format).
  - **updated_at** (str) - The timestamp when the asset was last updated (ISO 8601 format).

#### Response Example
```json
{
  "indexed_assets": [
    {
      "id": "6298d673f1090f1100476d4c",
      "index_id": "6298d673f1090f1100476d4c",
      "filename": "example.mp4",
      "duration": 10.5,
      "fps": 30.0,
      "width": 1920,
      "height": 1080,
      "size": 50000000,
      "created_at": "2024-08-16T16:53:59Z",
      "updated_at": "2024-08-16T16:53:59Z"
    }
  ]
}
```
```

--------------------------------

### GET /embed/v2/tasks

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves a paginated list of embedding tasks. You can filter tasks by creation date, status, and pagination parameters.

```APIDOC
## GET /embed/v2/tasks

### Description
Retrieves a paginated list of embedding tasks. You can filter tasks by creation date, status, and pagination parameters.

### Method
GET

### Endpoint
/embed/v2/tasks

### Parameters
#### Query Parameters
- **started_at** (string) - Optional - Retrieve the embedding tasks that were created after the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").
- **ended_at** (string) - Optional - Retrieve the embedding tasks that were created before the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").
- **status** (string) - Optional - Filter the embedding tasks by their current status. Values: `processing`, `ready`, or `failed`.
- **page** (integer) - Optional - A number that identifies the page to retrieve. Default: `1`.
- **page_limit** (integer) - Optional - The number of items to return on each page. Default: `10`. Max: `50`.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **tasks** (array) - A list of embedding tasks.
- **total** (integer) - The total number of tasks available.
- **page** (integer) - The current page number.
- **page_limit** (integer) - The number of items per page.

#### Response Example
```json
{
  "tasks": [
    {
      "id": "654f7a2a901234567890abcd",
      "status": "ready",
      "created_at": "2023-11-14T10:00:00Z",
      "updated_at": "2023-11-14T10:05:00Z",
      "auto_create_thumbnails": false,
      "notify_url": null,
      "metadata": {},
      "source_type": "video",
      "media_url": "https://user-bucket.com/video/long-video.mp4",
      "thumbnail_url": null,
      "error_message": null
    }
  ],
  "total": 1,
  "page": 1,
  "page_limit": 10
}
```
```

--------------------------------

### POST /tasks

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Creates a video indexing task, uploading and indexing a video in a single operation. This is a legacy endpoint and will be removed in a future release. Use the separated workflow of uploading via POST /assets and then indexing via POST /indexes/{index-id}/indexed-assets for new implementations.

```APIDOC
## POST /tasks

### Description
This method creates a video indexing task that uploads and indexes a video in a single operation. It supports uploading via a local file (`video_file`) or a publicly accessible URL (`video_url`). Video files must meet specific requirements for search (Marengo) and video analysis (Pegasus). This method allows uploads up to 2 GB; for larger files, use the Multipart Upload API. This endpoint is rate-limited.

<Warning title="Legacy endpoint">
This endpoint bundles two operations (upload and indexing) together. In the next major API release, this endpoint will be removed in favor of a separated workflow:
1. Upload your video using the [`POST /assets`](/v1.3/api-reference/upload-content/direct-uploads/create) endpoint
2. Index the uploaded video using the [`POST /indexes/{index-id}/indexed-assets`](/v1.3/api-reference/index-content/create) endpoint

This separation provides better control, reusability of assets, and improved error handling. New implementations should use the new workflow.
</Warning>

<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

### Method
POST

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **page** (int) - Optional - A number that identifies the page to retrieve. Default: `1`.
- **page_limit** (int) - Optional - The number of items to return on each page. Default: `10`. Max: `50`.
- **sort_by** (str) - Optional - The field to sort on. Available options: `updated_at`, `created_at`. Default: `created_at`.
- **sort_option** (str) - Optional - The sorting direction. Available options: `asc`, `desc`. Default: `desc`.
- **index_id** (str) - Optional - Filter by the unique identifier of an index.
- **status** (str or Sequence[str]) - Optional - Filter by one or more video indexing task statuses. Available options: `ready`, `uploading`, `validating`, `pending`, `queued`, `indexing`, `failed`. To filter by multiple statuses, specify the `status` parameter for each value (e.g., `status=ready&status=validating`).
- **filename** (str) - Optional - Filter by filename.
- **duration** (float) - Optional - Filter by duration in seconds.
- **width** (int) - Optional - Filter by width.
- **height** (int) - Optional - Filter by height.
- **created_at** (str) - Optional - Filter video indexing tasks by the creation date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). Returns tasks created on or after the specified time.
- **updated_at** (str) - Optional - Filter video indexing tasks by the last update date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). Returns tasks updated on or after the specified time.

#### Request Body
- **video_url** (str) - Required if `video_file` is not provided - The URL of the video to index.
- **video_file** (file) - Required if `video_url` is not provided - The video file to index.
- **index_id** (str) - Required - The unique identifier of the index to associate the video with.
- **enable_search** (bool) - Optional - Whether to enable search for the video. Default: `true`.
- **enable_deep_analysis** (bool) - Optional - Whether to enable deep analysis for the video. Default: `false`.

### Request Example
```json
{
  "video_url": "https://example.com/video.mp4",
  "index_id": "your_index_id"
}
```

### Response
#### Success Response (200)
- **task_id** (str) - The unique identifier of the created task.
- **status** (str) - The status of the task.
- **created_at** (str) - The timestamp when the task was created.

#### Response Example
```json
{
  "task_id": "task_abc123",
  "status": "queued",
  "created_at": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Get Task Transfer Status using Python

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves the status of a task transfer. Requires the integration ID associated with the transfer.

```python
from twelvelabs import TwelveLabs

client = TwelveLabs(
    api_key="YOUR_API_KEY",
)
client.tasks.transfers.get_status(
    integration_id="integration-id",
)
```

--------------------------------

### GET /indexes/{index_id}/videos/{video_id}

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves information about a specific video within an index. This method is deprecated and a new implementation should be used.

```APIDOC
## GET /indexes/{index_id}/videos/{video_id}

### Description
Retrieves information about the specified video. This method is deprecated in favor of the 'Retrieve an indexed asset' method.

### Method
GET

### Endpoint
`/indexes/{index_id}/videos/{video_id}`

### Parameters
#### Path Parameters
- **index_id** (str) - Required - The unique identifier of the index.
- **video_id** (str) - Required - The unique identifier of the video.

#### Query Parameters
- **transcription** (bool) - Optional - Whether to include transcription data.
- **page** (int) - Optional - The page number to retrieve. Defaults to 1.
- **page_limit** (int) - Optional - The number of items per page. Defaults to 10. Max is 50.
- **sort_by** (str) - Optional - The field to sort on. Available options: `updated_at`, `created_at`. Defaults to `created_at`.
- **sort_option** (str) - Optional - The sorting direction. Available options: `asc`, `desc`. Defaults to `desc`.
- **filename** (str) - Optional - Filter by filename.
- **duration** (float) - Optional - Filter by duration in seconds.
- **fps** (float) - Optional - Filter by frames per second.
- **width** (float) - Optional - Filter by width.
- **height** (int) - Optional - Filter by height.
- **size** (float) - Optional - Filter by size in bytes.
- **created_at** (str) - Optional - Filter by the creation date and time of the associated indexing tasks (RFC 3339 format).
- **updated_at** (str) - Optional - Filter by the last update date and time (RFC 3339 format).
- **user_metadata** (dict) - Optional - Filter by custom user-defined metadata.
- **request_options** (object) - Optional - Request-specific configuration.

### Request Example
```python
# This is a conceptual example, actual implementation may vary
client.indexes.videos.retrieve(
    index_id="6298d673f1090f1100476d4c",
    video_id="6298d673f1090f1100476d4c",
    transcription=True
)
```

### Response
#### Success Response (200)
- **video_data** (object) - Contains detailed information about the video.

#### Response Example
```json
{
  "video_data": {
    "id": "6298d673f1090f1100476d4c",
    "index_id": "6298d673f1090f1100476d4c",
    "status": "processed",
    "duration": 120.5,
    "fps": 30.0,
    "width": 1920,
    "height": 1080,
    "size": 50000000,
    "created_at": "2023-01-01T10:00:00Z",
    "updated_at": "2023-01-01T10:05:00Z",
    "filename": "example.mp4",
    "metadata": {},
    "transcription": {
      "status": "completed",
      "text": "This is a sample transcription."
    }
  }
}
```
```

--------------------------------

### Generate Video Summaries, Chapters, and Highlights with Python

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/README.md

This code snippet demonstrates how to use the TwelveLabs Python SDK to generate summaries, chapters, or highlights for a given video. It requires a video ID and a type parameter ('summary', 'chapter', or 'highlight'). An optional prompt can be provided for customized output.

```python
res = client.summarize(video_id="<YOUR_VIDEO_ID>", type="<TYPE>", prompt="<YOUR_PROMPT>")
if res.summarize_type == "summary":
    print(f"{res.summary}")
elif res.summarize_type == "chapter":
    print(f"Chapters: {res.chapters}")
elif res.summarize_type == "highlight":
    print(f"Highlights: {res.highlights}")
```

--------------------------------

### GET /indexes/{index_id}/indexed-assets/{indexed_asset_id}

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Retrieves detailed information about a specific indexed asset, including its status, metadata, and optional embeddings or transcriptions.

```APIDOC
## GET /indexes/{index_id}/indexed-assets/{indexed_asset_id}

### Description
This method retrieves information about an indexed asset, including its status, metadata, and optional embeddings or transcription. Use this to monitor indexing progress, retrieve asset metadata, or get embeddings and transcriptions if enabled.

### Method
GET

### Endpoint
`/indexes/{index_id}/indexed-assets/{indexed_asset_id}`

### Parameters
#### Path Parameters
- **index_id** (str) - Required - The unique identifier of the index to which the indexed asset has been uploaded.
- **indexed_asset_id** (str) - Required - The unique identifier of the indexed asset to retrieve.

#### Query Parameters
- **embedding_option** (Optional[Union[IndexedAssetsRetrieveRequestEmbeddingOptionItem, Sequence[IndexedAssetsRetrieveRequestEmbeddingOptionItem]]]) - Optional - Specifies which types of embeddings to retrieve. Possible values depend on the model version (e.g., `visual`, `audio`, `transcription` for Marengo 3.0; `visual-text`, `audio` for Marengo 2.7). Requires the asset to be indexed with the appropriate model.
- **transcription** (Optional[bool]) - Optional - If true, retrieves a transcription of the spoken words in the video.
- **request_options** (Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from twelvelabs import TwelveLabs

client = TwelveLabs(
    api_key="YOUR_API_KEY",
)
client.indexes.indexed_assets.retrieve(
    index_id="6298d673f1090f1100476d4c",
    indexed_asset_id="6298d673f1090f1100476d4c",
    transcription=True,
)
```

### Response
#### Success Response (200)
- **status** (str) - The current status of the indexed asset (e.g., 'processing', 'ready').
- **metadata** (object) - Contains system and user-defined metadata for the asset.
- **embeddings** (object) - Optional. Contains embeddings if requested and available.
- **transcription** (object) - Optional. Contains the transcription if requested and available.

#### Response Example
```json
{
  "status": "ready",
  "metadata": {
    "duration": 120.5,
    "resolution": "1920x1080",
    "filename": "my_video.mp4"
  },
  "embeddings": {
    "visual": [
      // ... visual embeddings data
    ]
  },
  "transcription": {
    // ... transcription data
  }
}
```
```

--------------------------------

### POST /indexes

Source: https://github.com/twelvelabs-io/twelvelabs-python/blob/main/reference.md

Creates a new index with specified models, addons, and name. Addons like thumbnails can be enabled, but only with the Marengo model.

```APIDOC
## POST /indexes

### Description
This method creates an index.

### Method
POST

### Endpoint
/indexes

### Parameters
#### Request Body
- **index_name** (str) - Required - The name of the index. Make sure you use a succinct and descriptive name.
- **models** (Sequence[IndexesCreateRequestModelsItem]) - Required - An array that specifies the video understanding models and the model options to be enabled for this index. Models determine what tasks you can perform with your videos. Model options determine which modalities the platform analyzes.
- **addons** (Optional[Sequence[str]]) - Optional - An array specifying which add-ons should be enabled. The following values are supported: `thumbnail`. If not provided, no add-ons will be enabled. Note: Addons can only be enabled when using the Marengo video understanding model and cannot be disabled after creation.
- **request_options** (Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
{
  "index_name": "myIndex",
  "models": [
    {
      "model_name": "marengo3.0",
      "model_options": ["visual", "audio"]
    },
    {
      "model_name": "pegasus1.2",
      "model_options": ["visual", "audio"]
    }
  ],
  "addons": ["thumbnail"]
}
```

### Response
#### Success Response (200)
- **message** (str) - Success message.
- **index** (object) - Details of the created index.
  - **id** (str) - The unique identifier of the index.
  - **name** (str) - The name of the index.
  - **status** (str) - The status of the index.
  - **created_at** (str) - The timestamp when the index was created.
  - **updated_at** (str) - The timestamp when the index was last updated.
  - **models** (Array) - Details about the models used for the index.
  - **addons** (Array) - Details about the enabled addons.

#### Response Example
```json
{
  "message": "Index created successfully.",
  "index": {
    "id": "6298d673f1090f1100476d4c",
    "name": "myIndex",
    "status": "created",
    "created_at": "2023-10-27T10:00:00Z",
    "updated_at": "2023-10-27T10:00:00Z",
    "models": [
      {
        "name": "marengo3.0",
        "options": ["visual", "audio"]
      },
      {
        "name": "pegasus1.2",
        "options": ["visual", "audio"]
      }
    ],
    "addons": ["thumbnail"]
  }
}
```
```