Create indexes

An index is a basic unit for organizing and storing your video data (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:

  • To generate text from video, use Pegasus. For search and classification, use Marengo.
  • 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. See the Retrieve thumbnails page for details.

For a description of each field in the request and response, see the API Reference > Create an index page.


  • You’re familiar with the concepts that are described on the Platform overview page.
  • You have a valid Twelve Labs account. For details about creating an account and retrieving your API key, see the Authentication page.


Follow the steps in the guide below to create an index.