Recipes

Search videos

Find specific moments, topics, or content across your video collection using natural language. Returns structured results with video references, timestamps, and relevance context.

Prerequisites

  • Complete the Quickstart to create a knowledge store with at least one item in ready status.
  • Read Create a response to understand the request and response format.

When to use this

  • Finding specific content in a large collection
  • Locating moments that match a visual or semantic description
  • Building search features in your application

Search with structured results

Describe what you are looking for in plain language. The schema captures video references, timestamps, descriptions, and relevance scores so you can process results programmatically.

1import json
2import requests
3
4API_KEY = "YOUR_API_KEY"
5BASE_URL = "https://api.twelvelabs.io/v1.3"
6HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
7STORE_ID = "your_knowledge_store_id"
8
9search_schema = {
10    "type": "object",
11    "properties": {
12        "results": {
13            "type": "array",
14            "items": {
15                "type": "object",
16                "properties": {
17                    "video_reference": {"type": "string"},
18                    "timestamp": {"type": "string"},
19                    "description": {"type": "string"},
20                    "relevance": {"type": "string"}
21                }
22            }
23        },
24        "total_results": {"type": "integer"},
25        "query_interpretation": {"type": "string"}
26    }
27}
28
29response = requests.post(
30    f"{BASE_URL}/responses",
31    headers=HEADERS,
32    json={
33        "model": "jockey1.0",
34        "input": [
35            {"type": "message", "role": "user", "content": "Find all moments where someone is presenting to an audience"}
36        ],
37        "knowledge_store_id": STORE_ID,
38        "text": {"format": {"type": "json_schema", "name": "search_results", "schema": search_schema}}
39    }
40)
41
42result = response.json()
43for output in result["output"]:
44    if output["type"] == "message":
45        for content in output["content"]:
46            search = json.loads(content["text"])
47            print(f"Found {search['total_results']} results")
48            print(f"Interpreted as: {search['query_interpretation']}\n")
49            for r in search["results"]:
50                print(f"  [{r['timestamp']}] {r['video_reference']}")
51                print(f"    {r['description']}")
52                print(f"    Relevance: {r['relevance']}\n")

Example prompts

These prompts illustrate the range of searches you can run. Jockey matches against visual content, audio, text on screen, and semantic meaning.

PromptWhat it finds
”someone laughing”Moments with laughter
”product being held up to camera”Product showcase moments
”outdoor scenes with water”Nature and water visuals
”heated discussion”Tense conversational moments
”text on screen”Moments with overlaid text or titles

Variations

  • Narrow by context: Add instructions like “Only search the first 2 minutes of each video”
  • Ranked results: “Find and rank the top 5 most visually striking moments”
  • Multi-turn refinement: Search, then follow up with “Show me more like the third result” using a multi-turn session

Jupyter notebook

Download the notebook to run this recipe interactively.

See also