Create indexes
An index is a basic unit for organizing and storing video data consisting of video embeddings and metadata. Indexes facilitate information retrieval and processing.
You can use indexes to group related videos. For example, if you want to upload multiple videos from a car race, you can create a single index and upload all the videos to it. After uploading, you can search for specific moments across all videos in that index in a single request.
When creating a new index, you must specify at least the following information:
- Name: Use a brief and descriptive name to facilitate future reference and management. Index names must be unique and cannot be duplicated.
- Model configuration: Provide a list containing the video understanding models and the associated model options you want to enable.
Note the following about model configurations:
- The model configuration determines the downstream tasks you can perform on the videos uploaded to this index. Use Pegasus to generate text from video. Use Marengo to search and create embeddings.
- The models and the model options specified when you create an index apply to all the videos you upload to that index and cannot be changed.
- To activate the thumbnail generation feature, include an array named
addons
in your request that contains thethumbnail
value.
For a description of each field in the request and response, see the API Reference > Create an index page.
Prerequisites
- You’re familiar with the concepts that are described on the Platform overview page.
- You have an API key. To retrieve your API key, navigate to the API Key page and log in with your credentials. Then, select the Copy icon to the right of your API key to copy it to your clipboard.
Procedure
-
Import the SDK into your application:
from twelvelabs import TwelveLabs
import { TwelveLabs } from 'twelvelabs-js';
-
Instantiate the SDK client with your API key:
client = TwelveLabs(api_key="<YOUR_API_KEY>")
const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>' });
-
Specify the desired model configuration.
-
The example below enables the Marengo video understanding model and the
visual
andaudio
model options:models = [ { "name": "marengo2.7", "options": ["visual", "audio"] } ]
const models = [ { name: 'marengo2.7', options: ['visual', 'audio'], }, ];
-
The example below enables the Pegasus video understanding model and the
visual
andaudio
model options:models = [ { "name": "pegasus1.1", "options": ["visual", "audio"] } ]
const models = [ { name: 'pegasus1.1', options: ['visual', 'audio'], }, ];
-
The example code below enables both the Marengo and Pegasus video understanding models:
models = [ { "name": "marengo2.7", "options": ["visual", "audio"] }, { "name": "pegasus1.1", "options": ["visual", "audio"] } ]
const models = [ { name: 'marengo2.7', options: ['visual', 'audio'], }, { name: 'pegasus1.1', options: ['visual', 'audio'], }, ];
-
-
To create a new index, invoke the
create
method of theclient.index
object with the following parameters:name
: A string representing the name of your new index. Choose a succinct and descriptive name for your index.models
: An object specifying your model configuration. You constructed this object in the previous step.- (Optional)
addons
: An array of strings specifying the add-ons you want to enable for your index. This example enables the thumbnail generation feature.
index = client.index.create( name="<YOUR_INDEX_NAME>", models=models, addons=["thumbnail"] # Optional ) print(f"A new index has been created: id={index.id} name={index.name} models={index.models}")
let index = await client.index.create({ name: '<YOUR_INDEX_NAME>', models: models, addons: ['thumbnail'], // Optional }); console.log(`A new index has been created: id=${index.id} name=${index.name} models=${JSON.stringify(index.models)}`);
The response should look similar to the following one:
A new index has been created: id=65d345106efba5e3988d6d4b name=index-01 models=[Model(name='marengo2.7', options=['visual', 'audio'], addons=['thumbnail'])]
Note that the response contains, among other information, a field named
id
, representing the unique identifier of your new index.
Updated 5 days ago