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, Twelve Labs recommends you create a single index and upload all the videos to it. Then, to find a specific moment in that race, you call the /search endpoint once, passing it the unique identifier of the index.

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.
  • Engine configuration: Provide a list containing the video understanding engines and the associated engine options you want to enable.

Note the following about engine configurations:

  • The engine configuration determines the downstream tasks you can perform on the videos uploaded to this index. Use Pegasus to generate text from video. Use Marengo for search and classification.
  • The engines and the engine options specified when you create an index apply to all the videos you upload to that index and cannot be changed.
  • When using the Marengo family of video understanding engines, specify any combination of the available engine options: visual, conversation, text_in_video, andlogo.
  • When using the Pegasus family of video understanding engines, specify one or both of the following engine options: visual and conversation.
  • To activate the thumbnail generation feature, include an array named addons in your request that contains the thumbnail 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 Dashboard 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

  1. Import the SDK into your application:

    from twelvelabs import TwelveLabs
    
    import { TwelveLabs } from 'twelvelabs-js';
    
  2. Instantiate the SDK client with your API key:

    client = TwelveLabs(api_key="<YOUR_API_KEY>")
    
    const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY' });
    
  3. Specify the desired engine configuration.

    • The example below enables the Marengo video understanding engine and the following engine options - visual, conversation, text_in_video, and logo:

      engines = [
              {
                "name": "marengo2.6",
                "options": ["visual", "conversation", "text_in_video", "logo"]
              }
        ]
      
      const engines = [
        {
          name: 'marengo2.6',
          options: ['visual', 'conversation', 'text_in_video', 'logo'],
        },
      ];
      
    • The example below enables the Pegasus video understanding engine and the following engine options- visual and conversation:

      engines = [
              {
                  "name": "pegasus1",
                  "options": ["visual", "conversation"]
              }
          ]
      
      const engines = [
        {
          name: 'pegasus1',
          options: ['visual', 'conversation'],
        },
      ];
      
    • The example code below enables both the Marengo and Pegasus video understanding engines:

      engines = [
              {
                  "name": "pegasus1",
                  "options": ["visual", "conversation"]
              },
              {
                "name": "marengo2.6",
                "options": ["visual", "conversation", "text_in_video", "logo"]
              }
          ]
      
      const engines = [
        {
          name: 'marengo2.6',
          options: ['visual', 'conversation', 'text_in_video', 'logo'],
        },
        {
          name: 'pegasus1',
          options: ['visual', 'conversation'],
        },
      ];
      
  4. To create a new index, invoke the create method of the client.index object with the following parameters:

    • name: with the name of your new index. Choose a succinct and descriptive name for your index.
    • engines: with your engine configuration.
    • (Optional) addons: with an array 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>",
        engines=engines,
        addons=["thumbnail"] # Optional
    )
    print(f"A new index has been created: id={index.id} name={index.name} engines={index.engines}")
    
    let index = await client.index.create({
      name: '<YOUR_INDEX_NAME>',
      engines: engines,
      addons: ['thumbnail'], // Optional
    });
    console.log(`A new index has been created: id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)}`);
    

    The response should look similar to the following one:

    A new index has been created: id=65d345106efba5e3988d6d4b name=index-01 engines=[Engine(name='marengo2.6', options=['visual', 'conversation', 'text_in_video', 'logo'], addons=None)]
    

    Note that the response contains, among other information, a field named id, representing the unique identifier of your new index.