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.

Prerequisites

• 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: 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.

• 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:
    Shell

    python -m pip install requests pprint
    

  • For Node.js: Install theaxios and form-data packages by entering the following command:
    Shell

    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:
     Shell

     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.

Retrieve information

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