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

  1. Create an index​
  2. Upload a video​
  3. Make a search request​

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.


  • A valid Twelve Labs account.



    The Twelve Labs Video Understanding API is currently in closed beta. To create an account, you must first sign up for a demo. To do so, go to the Request a Demo page and follow the instructions. You will receive a signup code that you can use to create an account.

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

  • Your video must meet the following requirements:

    • Video resolution: must be greater or equal than 360p and less than 1080p (FHD)
    • Duration: must be between 10 seconds and 2 hours (7,200s)
      If you require different options, send us an email at support[at]twelvelabs.io.
  • 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 button under the API Key section:

    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 one or more video vectors and is the most granular level at which you can perform a search. 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 API service will automatically create a rich set of vectors containing all the information it needs to perform fast, semantic, accurate, and scalable searches. Follow the steps in the guide below to upload a video.

Make a search request

When the API service has finished indexing the video, it can be searched by using the /search endpoint. Follow the steps in the guide below to make a search request.

Related topics