{"id":8731,"library":"twelvelabs","title":"TwelveLabs Python SDK","description":"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.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/twelvelabs-io/twelvelabs-python","tags":["video","ai","sdk","multimodal","search","embeddings","analysis"],"install":[{"cmd":"pip install twelvelabs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python version >=3.8 and <4.0","package":"Python","optional":false}],"imports":[{"symbol":"TwelveLabs","correct":"from twelvelabs import TwelveLabs"},{"note":"Required for specifying models when creating an index.","symbol":"IndexesCreateRequestModelsItem","correct":"from twelvelabs.indexes import IndexesCreateRequestModelsItem"}],"quickstart":{"code":"import os\nfrom twelvelabs import TwelveLabs\n\n# It is recommended to set your API key as an environment variable:\n# export TWELVELABS_API_KEY=\"YOUR_API_KEY\"\napi_key = os.environ.get(\"TWELVELABS_API_KEY\", \"YOUR_API_KEY\")\n\nif api_key == \"YOUR_API_KEY\":\n    print(\"WARNING: Please set the 'TWELVELABS_API_KEY' environment variable or replace 'YOUR_API_KEY' in the code.\")\n    print(\"This quickstart will likely fail API calls without a valid key.\")\n\ntry:\n    client = TwelveLabs(api_key=api_key)\n    print(\"Successfully initialized TwelveLabs client.\")\n    \n    # Example: List existing indexes to verify connection and authentication\n    indexes_response = client.indexes.list()\n    indexes = indexes_response.data # Access the 'data' attribute for the list of indexes\n    print(f\"Found {len(indexes)} existing indexes:\")\n    for idx in indexes:\n        print(f\"- {idx.name} (ID: {idx.id}, Status: {idx.status})\")\n\nexcept Exception as e:\n    print(f\"An error occurred during client initialization or API call: {e}\")","lang":"python","description":"Initializes the TwelveLabs client using an API key from an environment variable and lists existing indexes to confirm a successful connection."},"warnings":[{"fix":"Refer to the official migration guides and documentation for detailed instructions on updating your code (e.g., API parameter changes, object structures).","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Consult the TwelveLabs release notes and migration guides for Marengo 3.0 to update model names and options in your `IndexesCreateRequestModelsItem`.","message":"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.","severity":"breaking","affected_versions":"From Marengo 2.x to Marengo 3.0"},{"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).","message":"Effective April 26, 2026, delete requests for referenced assets (assets still associated with an index) will be denied by default, changing previous behavior.","severity":"breaking","affected_versions":">=1.x.x (Effective April 26, 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.","message":"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.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The API key provided during client initialization is incorrect, has expired, or is missing.","error":"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."},{"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).","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.","error":"twelvelabs.errors.ConflictError: Index name {index_name} already exists. Please use another unique name and try again."},{"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.","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).","error":"twelvelabs.errors.BadRequestError: The {parameter} parameter is invalid."}]}