The platform uses a hierarchical structure to classify your videos. Groups of classes form the top level of the structure. and each group comprises multiple classes. Classes serve as the primary units of organization, meaning that your videos are categorized into classes. Each class contains multiple prompts that define its characteristics. The prompts act as building blocks for the classification system, enabling a precise placement of videos into relevant classes based on their content.

Historically, video classification was constrained to a predetermined set of classes, primarily targeting the recognition of events, actions, objects, and similar attributes. However, the Twelve Labs Video Understanding Platform now allows you to customize classification criteria without the need to retrain the model, eliminating the complexities associated with model training.

Follow the steps in this guide to classify your videos.

Classify Videos

  1. From the Indexes page, find the index containing the videos to be classified and select the Classify button:

  2. (Optional) The Playground offers a set of predefined classes, and it also allows you to add custom ones. To manage your classes, select the Edit button, which opens the Class Group page. Once there, refer to the Manage classes section for instructions:

  3. From the Select class group drop-down list, choose a group of classes:

  4. (Optional) By default, the Playground classifies your videos based on all the classes in the group you selected in the previous step. You can use the Filter by class drop-down list to narrow down the list of classes:

  5. To perform a classification request, select the Run button. The Playground will group the results by class. For each video clip, the Playground shows the name of the video file, a thumbnail from the middle of the video, the score, and the duration ratio.

  6. (Optional) You can expand the Advanced parameters section and set the following advanced parameters:

    1. Minimum video score: This slider allows you to filter on the confidence level that the video clips match the specified class.

    2. Minimum duration ratio: This slider allows you to filter on the duration ratio, which represents the sum of the lengths of the matching video clips inside a video divided by the total length of the video. By adjusting this slider, you can control the inclusion or exclusion of specific video clips based on their duration relative to the overall video length.

  7. (Optional) Use the View code button to view the code snippet that the platform used to perform this request. You can copy and paste it into your application.

Manage Classes

The Playground provides a set of predefined classes, but you can also add your own. This allows you to align the classification system with your unique needs.

  1. List of classes: Classes are displayed as a table, and each row represents a group.
  2. Select to classify: Opens the Classify page and prefills the Select Class Group drop-down with this class group.
  3. Three dots button: Provides quick access to commonly used actions that you can perform on a group.
  4. Create button: Allows you to create a new group of classes by uploading a JSON file or by using the user interface.

Create a Group

There are two ways in which you can create a group of classes:

Use the user interface

  1. From the Class groups page, select the Create button. Then, choose Create Class Group.

  2. In the Define your class group pane, enter the following information:

    1. Name: A brief and descriptive name for your group of classes
    2. Class name: The desired name for this class.
    3. Prompts: Use the Add Prompt button to add new prompts to this class
  3. (Optional) You can automatically generate prompts by using the Magic Prompt Generator button. You can then review the prompts and select the ones that are most relevant to your classification criteria. The magic prompt generator is a useful tool if you are looking to expand your classification criteria and streamline the prompt generation process.

  4. (Optional): You can add more classes to this group by selecting the Add class button.

  5. When you've finished, select the Save button.

Upload a JSON file

To create a group by uploading a JSON file, the format of your file should be similar to the example shown below:

    "name": "DanceTok",
    "prompts": [
      "Dance tutorial",
      "Dance group",
      "Dance competition"
    "name": "CookTok",
    "prompts": [
      "Cooking tutorial",
      "Cooking ustensils review"



When you upload a JSON file, the Playground will automatically assign the name of the file as the name of the group.

  1. From the Class groups page, select the Create button. Then, choose Upload JSON.
  2. Choose the files that you want to upload.
  3. (Optional) Review the list of files to be uploaded. To remove a file, select the X icon located at the right.
  4. When you've finished, select the Upload button.

Edit a Group

  1. From the Class groups page, find the group that you want to edit, and select the three dots button located at the end of the row.
  2. From the menu, choose Edit.
  3. The remaining steps are similar to those for creating a group.

Remove a Group

  1. From the Class groups page, find the group that you want to remove, and select the three dots button located at the end of the row.
  2. From the menu, choose Delete.