This quickstart guide provides a simplified introduction to searching video content using the TwelveLabs Video Understanding Platform. It includes:

• A basic working example
• Minimal implementation details
• Core parameters for common use cases

For a comprehensive guide, see the Search page.

Prerequisites

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

• Ensure the TwelveLabs SDK is installed on your computer:

  PythonNode.js

  $
  pip install twelvelabs

• The videos you wish to use 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: Your video files 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: Must be between 4 seconds and 2 hours (7,200s).
  • File size: Must not exceed 2 GB.
    If you require different options, contact us at support@twelvelabs.io.

Starter code

Copy and paste the code below to make a search request, replacing the placeholders surrounded by <> with your values.

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
index = client.index.create(name="<YOUR_INDEX_NAME>", models=[{"name": "marengo2.7","options": ["visual", "audio"],}])
6
print(f"Created index: id={index.id} name={index.name}")
7
task = client.task.create(index_id=index.id, url="<YOUR_VIDEO_URL>")
8
print(f"Created task: id={task.id}")
9
10
task.wait_for_done(sleep_interval=50, callback=lambda t: print(f"  Status={t.status}"))
11
if task.status != "ready":
12
    raise RuntimeError(f"Indexing failed with status {task.status}")
13
print(f"Upload complete. The unique identifier of your video is {task.video_id}.")
14
15
search_results = client.search.query(index_id=index.id, query_text="<YOUR_QUERY>", options=["visual", "audio"])
16
for clip in search_results.data:
17
    print(f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence}")

Step-by-step guide