Skip to navigation

Quickstart

Jockey reasons across your videos and images and answers with grounded, cited moments. This page takes you from nothing to a first result through the API.

First you put your videos and images in a knowledge store, a collection that Jockey can search and reason across. That setup is the same every time. Then you choose how to get something back from it:

  • Search a knowledge store when you know what you are looking for. You describe it in plain language, and you receive the matching clips and images, ranked by how well they match. Nothing is interpreted or summarized, so you can show the results in your app or pass them to your own code.
  • Create a response when you have a question. Jockey plans its own steps, searches and reasons across everything in the knowledge store, and writes an answer that cites the moments it used.

Both work on the same knowledge store, so you can use one and then the other without uploading anything again.

4 steps, Python or Node.js

  1. 1Create a keyFree account
  2. 2InstallOne command
  3. 3RunChoose a response or a search
  4. 4Read resultsCited moments, or ranked clips
Prefer not to write code?

You can use Jockey without writing code. Start with the Jockey MCP connects it to Claude or ChatGPT in four steps, and you can ask questions about your videos right in the chat. The knowledge stores Jockey uses are also visible in Connect, where you can manage them.

1

Get an API key

Sign up for a free account, open the API Keys page, and create and copy a key.

2

Install the SDK

pip install --upgrade twelvelabs
3

Choose what you want to do and run its code

Both tabs start with the same setup: the starter code uploads your content, builds a knowledge store, and waits until it is ready. They differ only in the last request.

Public video URLs can be up to 4 GB, local videos up to 200 MB, and images up to 32 MB. Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported. Use a short clip for your first run.

Choose the tab that matches what you want back, then fill in the values in angle brackets, such as your API key and a link to your video, and run it.

If you wantChooseYou receive
The matching moments themselves, to show or process in your own codeSearch a knowledge storeClips and images, ranked by relevance
An answer to a question about your contentCreate a responseWritten text with the cited moments behind it

Ask a question. Jockey searches and reasons across your content, then answers in text and cites the moments it used.

from twelvelabs import TwelveLabs
import time
# Step 1: Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")
# Step 2: Upload a video or an image
asset = client.assets.create(method="url", url="<YOUR_MEDIA_URL>") # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
# Or use method="direct" and file=open("<YOUR_FILE_PATH>", "rb") to upload a local file up to 200 MB
print(f"Asset created: {asset.id}")
# Step 3: Check the status of the asset
while True:
status = client.assets.retrieve(asset_id=asset.id).status
if status == "ready":
break
elif status == "failed":
raise Exception("Asset processing failed")
print(f"Status: {status}, waiting...")
time.sleep(5)
print("Asset ready")
# Step 4: Create a knowledge store
store = client.knowledge_stores.create(name="<YOUR_KNOWLEDGE_STORE_NAME>")
print(f"Knowledge store created: {store.id}")
# Step 5: Add the asset to the knowledge store
item = client.knowledge_store_items.create(
knowledge_store_id=store.id,
asset_id=asset.id,
# asset_type="image", # Uncomment if your asset is an image (the default is video)
)
print(f"Item added: {item.id}")
# Step 6: Check the status of the knowledge store item
while True:
status = client.knowledge_store_items.retrieve(
knowledge_store_id=store.id, item_id=item.id
).status
if status == "ready":
break
elif status == "failed":
raise Exception("Indexing failed")
print(f"Status: {status}, waiting...")
time.sleep(10)
print("Indexing complete")
# Step 7: Generate a response
response = client.responses.create(
knowledge_store_id=store.id,
input=[{"type": "message", "role": "user", "content": "Give me an overview of this content - main themes, key subjects, and any patterns."}],
)
for output in response.output:
if output.type == "message":
for content in output.content:
print(content.text)
4

Read your results

When your code finishes, it prints the result of what you chose:

  • Create a response: Jockey’s answer to your question, as text.
  • Search a knowledge store: one line for each match, with its rank, its item identifier, and for a video, the start and end times of the clip.

Longer content takes longer to become ready.

A few terms

  • Asset: a file you uploaded. You can reuse it without uploading it again.
  • Knowledge store: a collection of your videos and images that Jockey can search and reason across.
  • Knowledge store item: an asset that you added to a knowledge store. It is ready to use when its status is ready.

Next steps

Each task has a full quickstart with an explanation of every part of the code, and the recipes show what else Jockey can do.

For more in-depth information on each task, see the guides: