Recipes

Get a corpus overview

Summarize an entire video collection - themes, subjects, content types, patterns, and key statistics - in a single request.

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

  • Starting work with a new collection and want to understand what’s in it
  • Feeding collection context to a downstream agent or pipeline
  • Generating collection summaries for a dashboard or UI

Get a plain text overview

Send a natural-language prompt asking for a summary. Jockey reasons across all videos in the knowledge store and returns a prose overview.

1import requests
2
3API_KEY = "YOUR_API_KEY"
4BASE_URL = "https://api.twelvelabs.io/v1.3"
5HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
6STORE_ID = "your_knowledge_store_id"
7
8response = requests.post(
9    f"{BASE_URL}/responses",
10    headers=HEADERS,
11    json={
12        "model": "jockey1.0",
13        "input": [
14            {"type": "message", "role": "user", "content": "Give me a comprehensive overview of this video collection. Include main themes, recurring subjects, content types, and any notable patterns."}
15        ],
16        "tools": [
17            {"type": "knowledge_store", "knowledge_store_id": STORE_ID}
18        ]
19    }
20)
21
22result = response.json()
23for output in result["output"]:
24    if output["type"] == "message":
25        for content in output["content"]:
26            print(content["text"])

Get a structured overview

Add a JSON Schema to get machine-readable output you can parse programmatically. The schema defines the fields Jockey fills in - video count, themes, content types, key subjects, and a summary.

1import json
2
3overview_schema = {
4    "type": "object",
5    "properties": {
6        "total_videos": {"type": "integer"},
7        "themes": {"type": "array", "items": {"type": "string"}},
8        "content_types": {"type": "array", "items": {"type": "string"}},
9        "key_subjects": {"type": "array", "items": {"type": "string"}},
10        "patterns": {"type": "array", "items": {"type": "string"}},
11        "summary": {"type": "string"}
12    }
13}
14
15response = requests.post(
16    f"{BASE_URL}/responses",
17    headers=HEADERS,
18    json={
19        "model": "jockey1.0",
20        "input": [
21            {"type": "message", "role": "user", "content": "Give me a structured overview of this video collection."}
22        ],
23        "tools": [
24            {"type": "knowledge_store", "knowledge_store_id": STORE_ID}
25        ],
26        "text": {"format": "json_schema", "json_schema": overview_schema}
27    }
28)
29
30result = response.json()
31for output in result["output"]:
32    if output["type"] == "message":
33        for content in output["content"]:
34            overview = json.loads(content["text"])
35            print(f"Videos: {overview['total_videos']}")
36            print(f"Themes: {', '.join(overview['themes'])}")
37            print(f"Summary: {overview['summary']}")

Variations

  • Domain-focused: Add instructions like “You are a media analyst” to shape the overview for a specific audience
  • Comparative: “How does this collection compare to a typical corporate training library?”
  • Gap analysis: “What topics are underrepresented in this collection?”

Jupyter notebook

Download the notebook to run this recipe interactively.

See also