TwelveLabs Python SDK

1.2.2 · active · verified Thu Apr 16

The TwelveLabs Python SDK provides a set of intuitive classes and methods that streamline platform interaction, minimizing the need for boilerplate code. It offers a robust interface for interacting with the TwelveLabs Video Understanding Platform, simplifying authentication and efficiently processing asynchronous tasks. The current version is 1.2.2 and releases are frequent, with breaking changes typically announced with major model updates or API shifts.

Common errors

```
twelvelabs.errors.AuthenticationError: API Key is either invalid or expired. Please check your API key or generate a new one from the dashboard and try again.
```
cause The API key provided during client initialization is incorrect, has expired, or is missing.

fix Ensure your `TWELVELABS_API_KEY` environment variable is correctly set, or that the `api_key` argument passed to `TwelveLabs()` is valid and current. Generate a new API key from the TwelveLabs dashboard if necessary.
```
twelvelabs.errors.ConflictError: Index name {index_name} already exists. Please use another unique name and try again.
```
cause An attempt was made to create a new index with a name that is already in use by another index in your TwelveLabs account.

fix Choose a unique name for your new index. Alternatively, before creating an index, use `client.indexes.list()` to check for existing indexes and handle potential name conflicts (e.g., delete the old index or reuse its ID).
```
twelvelabs.errors.BadRequestError: The {parameter} parameter is invalid.
```
cause A parameter in your API request (e.g., when creating an index, uploading a video, or performing a search) does not meet the API's validation rules (e.g., wrong data type, invalid value, missing required field).

fix Carefully review the specific error message to identify the problematic parameter. Consult the TwelveLabs Python SDK documentation or API reference for that particular method to ensure all parameters are correctly formatted and contain valid values.

Warnings

breaking Major breaking changes were introduced in versions 1.x.x compared to 0.4.x. Existing applications using 0.4.x require significant code updates and thorough testing when migrating to 1.x.x.
Fix: Refer to the official migration guides and documentation for detailed instructions on updating your code (e.g., API parameter changes, object structures).
breaking The Marengo 3.0 model update (March 11, 2026) introduced breaking changes that necessitate code modifications, particularly in how models are specified and used for indexing and search.
Fix: Consult the TwelveLabs release notes and migration guides for Marengo 3.0 to update model names and options in your `IndexesCreateRequestModelsItem`.
breaking Effective April 26, 2026, delete requests for referenced assets (assets still associated with an index) will be denied by default, changing previous behavior.
Fix: Update your deletion workflow to first delete any associated indexed assets or explicitly detach assets from indexes before attempting to delete the raw asset. Use the `force` query parameter on the DELETE method for assets if you intend to override this behavior (use with caution).
deprecated The Marengo 2.7 model was sunset on March 30, 2026. The `/gist` and `/summarize` endpoints for video analysis were removed on February 15, 2026.
Fix: Migrate from Marengo 2.7 to Marengo 3.0 or later. Replace usage of `/gist` and `/summarize` with the `/analyze` endpoint, which offers more flexible and structured text generation capabilities.

Install

pip install twelvelabs Install latest version

Imports

TwelveLabs
```
from twelvelabs import TwelveLabs
```
IndexesCreateRequestModelsItem
```
from twelvelabs.indexes import IndexesCreateRequestModelsItem
```
Required for specifying models when creating an index.

Quickstart

Initializes the TwelveLabs client using an API key from an environment variable and lists existing indexes to confirm a successful connection.

import os
from twelvelabs import TwelveLabs

# It is recommended to set your API key as an environment variable:
# export TWELVELABS_API_KEY="YOUR_API_KEY"
api_key = os.environ.get("TWELVELABS_API_KEY", "YOUR_API_KEY")

if api_key == "YOUR_API_KEY":
    print("WARNING: Please set the 'TWELVELABS_API_KEY' environment variable or replace 'YOUR_API_KEY' in the code.")
    print("This quickstart will likely fail API calls without a valid key.")

try:
    client = TwelveLabs(api_key=api_key)
    print("Successfully initialized TwelveLabs client.")
    
    # Example: List existing indexes to verify connection and authentication
    indexes_response = client.indexes.list()
    indexes = indexes_response.data # Access the 'data' attribute for the list of indexes
    print(f"Found {len(indexes)} existing indexes:")
    for idx in indexes:
        print(f"- {idx.name} (ID: {idx.id}, Status: {idx.status})")

except Exception as e:
    print(f"An error occurred during client initialization or API call: {e}")

view raw JSON →