Get Started

Quickstart

Important

The 1.3 version of the API includes significant improvements and introduces breaking changes. If you are using v1.2, refer to the Migration guide page for a detailed list of changes, migration instructions, and code examples.

This guide demonstrates building a production-ready video understanding service using a three-step process:

  1. Create an index
  2. Upload videos
  3. Perform downstream tasks.

The following diagram illustrates the steps in this guide:

Each step is composed of a single API call.

Start building

You can interact with the platform using one of the available SDKs or an HTTP client like requests or axios. This section demonstrates how to use the SDKs, the recommended approach for most scenarios.

Explore these quickstart notebooks containing complete, executable code that you can customize and extend:

CapabilityDescriptionTry it
SearchFind specific moments in your videos using text or image queries.Open In Colab
GenerateGenerate summaries and open-ended texts based on your videos.Open In Colab
EmbedCreate multimodal embeddings.Open In Colab

Prerequisites

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

  • To use the platform, you need an API key:

    1

    If you don’t have an account, sign up for a free account.

    2

    Go to the API Key page.

    3

    Select the Copy icon next to your key.

  • The videos you wish to upload must meet the following requirements:

    • Video resolution: Must be at least 360x360 and must not exceed 3840x2160.
    • Aspect ratio: Must be one of 1:1, 4:3, 4:5, 5:4, 16:9, or 9:16.
    • 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 support@twelvelabs.io.
    • Duration: For Marengo, it must be between 4 seconds and 2 hours (7,200s). For Pegasus, it must be between 4 seconds and 60 minutes (3600s). 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 support@twelvelabs.io.

  • Depending on the programming language you are using, install the TwelveLabs SDK by entering one of the following commands:

    $pip install twelvelabs

Procedure

You can interact with the platform using one of the available SDKs or an HTTP client like requests or axios.

Follow the steps in one of the sections below, depending on what task you want to complete. Note that the recommended approach for most scenarios is to use the SDKs.