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

  1. Create an index​
  2. Upload a video​
  3. Retrieve information by making a search or classification request.

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.
    • Duration: must be between 4 seconds and 2 hours (7,200s).
      If you require different options, send us an email at [email protected].
    • Audio track: If the conversation indexing option is selected, the video you're uploading must contain an audio track.
  • Install the required packages. Depending on the programming language you use, enter one of the following commands:

    python -m pip install requests pprint
    npm install axios form-data



  • For consistent search results, Twelve Labs recommends you upload 360p videos.
  • To make calls to the API, you must include your secret key and specify the URL of the API. Twelve Labs recommends you use environment variables to pass configuration to your application. To retrieve your API key, go to the Dashboard page and select the Copy icon at the right of your API key.
    Then, enter the following commands, replacing the placeholder surrounded by <> with your API key:
    export API_KEY=<YOUR_API_KEY>
    export API_URL=https://api.twelvelabs.io/v1.1

Create an index

An index groups videos together and specifies a video understanding engine and a list of indexing options that the platform uses to process all the videos within that index. Follow the steps in the guide below to create an index.

Upload a video

Once you've created an index, you can upload a video. When the video has finished uploading, the platform will automatically create a rich set of video embeddings containing all the information it needs to perform fast and accurate semantic searches. Follow the steps in the guide below to upload a video.

Retrieve information

When the platform has finished indexing your video, the most common actions you can perform are making a search or classification request.