This guide demonstrates how to build a production-ready search, classification, or video-to-text generation service by using a three-step process:

  1. Create an index​
  2. Upload a video​
  3. Perform downstream tasks.

The following diagram illustrates the steps in this guide:

Note that each step is composed of a single API call.

This guide shows how to build an application that calls the Twelve Labs API using Python and Node.js. However, note that the API is compatible with most programming languages, and you can also use Postman or other REST clients to send requests and view responses.


  • Before you begin, sign up for a free account, or if you already have one, sign in.

  • This guide assumes you're familiar with the concepts that are described on the Platform overview page.

  • Your video must meet the following requirements:

    • Video resolution: Must be greater or equal than 360p and less or equal than 4K. For consistent search results, Twelve Labs recommends you upload 360p videos.
    • Duration: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 5 seconds and 30 minutes (1800s).
    • File size: Must not exceed 2 GB.
      If you require different options, send us an email at [email protected].
    • Audio track: If the conversation engine option is selected, the video you are uploading must contain an audio track.
  • Depending on the programming language you are using, ensure that the required packages are installed:

    • For Python: Install the requests and pprint packages by entering the following command:
      python -m pip install requests pprint
    • For Node.js: Install theaxios and form-data packages by entering the following command:
      npm install axios form-data
  • To invoke the API, you must include your API key in the request and specify the URL of the API.

    1. Retrieve your API key:
      1. Navigate to the Dashboard page and log in with your credentials.
      2. Locate your API key and select the Copy icon to the right of the key to copy it to your clipboard.
    2. Configure the API request:
      Twelve Labs recommends you use environment variables to pass configuration to your application. In a terminal window, enter the following commands, replacing <YOUR_API_KEY> with your API key:
      export API_KEY=<YOUR_API_KEY>
      export API_URL=https://api.twelvelabs.io/v1.2

Create an index

An index groups videos together, and for each index, you must specify a name and configure the video understanding engines you want to enable.

Upload a video

Once you've created an index, you can upload a video. When the video has finished uploading, the platform will index it, automatically creating a rich set of video embeddings.

Perform downstream tasks

When the platform has finished indexing your video, you can perform the following actions: