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        "knowledge_store_id": STORE_ID
17    }
18)
19
20result = response.json()
21for output in result["output"]:
22    if output["type"] == "message":
23        for content in output["content"]:
24            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        "knowledge_store_id": STORE_ID,
24        "text": {"format": {"type": "json_schema", "name": "corpus_overview", "schema": overview_schema}}
25    }
26)
27
28result = response.json()
29for output in result["output"]:
30    if output["type"] == "message":
31        for content in output["content"]:
32            overview = json.loads(content["text"])
33            print(f"Videos: {overview['total_videos']}")
34            print(f"Themes: {', '.join(overview['themes'])}")
35            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