twelvelabs

library1.2.7pypypi✓ verified 86d ago

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.

ai-ml llm-agents

pip install twelvelabs

package ↗homepage ↗

INSTALL

IMPORT

SIG · TWELVELABS

twelvelabs

ai-mlpythonv1.2.7

Install

4.2s avg

Import

1497ms

Disk

35MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.558s · 36.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.2s · import 1.435s · 36MB

35MB installed

● package 35MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TwelveLabs

✓ from twelvelabs import TwelveLabs

IndexesCreateRequestModelsItem

✓ from twelvelabs.indexes import IndexesCreateRequestModelsItem

Required for specifying models when creating an index.

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}")

Debug

Known issues

breakingMajor 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).

affects: >=1.0.0

breakingThe 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`.

affects: From Marengo 2.x to Marengo 3.0

breakingEffective 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).

affects: >=1.x.x (Effective April 26, 2026)

deprecatedThe 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.

affects: All versions

Errors

Common errors & fixes

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.

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.

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.

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.

Upgrade

Version history

1.2.7latest on PyPI · released Jun 8, 2026

Audit

Dependencies

PythonrequiredRequires Python version >=3.8 and <4.0

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/twelvelabs/ ↗

homepagehttps://twelvelabs.io ↗