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 video​s
  3. Perform downstream tasks.

The following diagram illustrates the steps in this guide:

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

Twelve Labs provides a REST API for interacting with the platform. This guide shows how to build applications that call the API using the Twelve Labs SDKs. Note that you can also directly interact with the API using most programming languages, or you can use Postman or other REST clients to send requests and view responses.


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

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

  • You have an API key. To retrieve your API key, navigate to the Dashboard page and log in with your credentials. Then, select the Copy icon to the right of your API key to copy it to your clipboard.

  • The videos you wish to upload 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.
    • Video and audio formats: The video files you wish to upload must be encoded in the video and audio formats listed on the FFmpeg Formats Documentation page. For videos in other formats, contact us at [email protected].
    • Duration: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 4 seconds and 20 minutes (1200s). In a future release, the maximum duration for Pegasus will be 2 hours (7,200 seconds).
    • File size: Must not exceed 2 GB.
      If you require different options, contact us 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, install the Twelve Labs SDK by entering one of the following commands:

    pip install twelvelabs
    yarn add twelvelabs-js


Follow the steps in one of the guides below, depending on what task you want to complete: