This recipe shows you how to summarize all your videos and images (themes, subjects, content types, patterns, and key statistics) in a single request. You can receive the overview as prose or as structured JSON.

Use cases:

• Collection onboarding: Summarize a new collection before starting development
• Dashboard generation: Create collection summaries for a UI or reporting tool
• Pipeline input: Feed collection context to a downstream agent or workflow

Key concepts

• Knowledge store: A persistent store of your videos and images plus the understanding the platform derives from them — spatiotemporal context, a typed ontology, and embeddings — that together enable corpus-level reasoning.
• Structured output: A JSON schema you provide with your request. Jockey constrains its output to match your schema, so you retrieve machine-readable results instead of plain text. For a guide on designing schemas and parsing responses, see the Structured output page.

Workflow

This recipe shows two approaches: a plain-text overview that needs only a prompt, and a structured overview that adds a JSON schema to define the output format. Jockey reasons across your knowledge store, identifies themes and patterns, and returns results in the format you chose. You can adapt this recipe to target a specific domain or ask a different question about your collection.

Prerequisites

• You’ve already created a knowledge store with at least one item in ready status. See the Quickstart page for details.
• You’re familiar with the request and response format. See the Create a response page for details.

Plain-text overview

Return the overview as prose. This approach needs only a prompt.

Example

Copy and paste the code below, replacing the placeholders surrounded by <> with your values.

1
from twelvelabs import TwelveLabs
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"
5
6
# Generate the overview
7
response = client.responses.create(
8
    knowledge_store_id=STORE_ID,
9
    input=[{"type": "message", "role": "user", "content": "Give me a comprehensive overview of these videos and images. Include main themes, recurring subjects, content types, and any notable patterns."}],
10
)
11
12
# Read the overview text
13
for output in response.output:
14
    if output.type == "message":
15
        for content in output.content:
16
            print(content.text)

Code explanation

Example response

The text field inside each content part contains Jockey’s overview formatted as Markdown. A typical response looks like this:

### Overall character
- **Content type:** product tutorials, customer interviews, and feature demos
- **Primary audience:** developers and product managers
- **Structure:** a growing library of short-form instructional and promotional content
### Main themes
- **Product onboarding**: step-by-step walkthroughs of initial setup and core workflows
- **Feature announcements**: quarterly release highlights and capability demos
- **Customer success**: interviews and testimonials from active users
### Recurring subjects
- Dashboard and analytics tooling
- API authentication and integration workflows
- Mobile SDK setup and troubleshooting
### Notable patterns
- Tutorial output clusters around product launch dates
- Most webinars include a Q&A segment in the final third
- Interview content appears on a quarterly cadence

Structured overview

Return the overview as JSON that matches a schema you define. Use this approach when downstream code expects typed fields.

Example

Copy and paste the code below, replacing the placeholders surrounded by <> with your values.

1
import json
2
from twelvelabs import TwelveLabs, TextParam
3
from twelvelabs.types.text_param_format import TextParamFormat_JsonSchema
4
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"
7
8
# Define a JSON schema for the overview
9
overview_schema = {
10
    "type": "object",
11
    "properties": {
12
        "total_items": {"type": "integer"},             # Number of items in the knowledge store
13
        "themes": {                                      # Recurring themes across items
14
            "type": "array",
15
            "items": {"type": "string"},
16
        },
17
        "content_types": {                               # Production formats (tutorial, demo, etc.)
18
            "type": "array",
19
            "items": {"type": "string"},
20
        },
21
        "key_subjects": {                                # Main subjects or topics covered
22
            "type": "array",
23
            "items": {"type": "string"},
24
        },
25
        "patterns": {                                    # Notable patterns or trends
26
            "type": "array",
27
            "items": {"type": "string"},
28
        },
29
        "summary": {"type": "string"},                  # Overall narrative summary
30
    },
31
}
32
33
# Generate the overview
34
response = client.responses.create(
35
    knowledge_store_id=STORE_ID,
36
    input=[{"type": "message", "role": "user", "content": "Give me a structured overview of these videos and images."}],
37
    text=TextParam(format=TextParamFormat_JsonSchema(name="corpus_overview", schema_=overview_schema)),
38
)
39
40
# Parse the JSON overview
41
for output in response.output:
42
    if output.type == "message":
43
        for content in output.content:
44
            overview = json.loads(content.text)
45
            print(f"Items: {overview['total_items']}")
46
            print(f"Themes: {', '.join(overview['themes'])}")
47
            print(f"Summary: {overview['summary']}")

Code explanation

Example response

The text field inside each content part is a JSON string that matches your schema. After parsing, a typical result looks like this:

1
{
2
  "total_items": 12,
3
  "themes": ["product onboarding", "feature announcements", "customer success", "API integration"],
4
  "content_types": ["tutorials", "demos", "webinars", "interviews"],
5
  "key_subjects": ["analytics dashboard", "API authentication", "mobile SDK", "billing workflows"],
6
  "patterns": ["tutorial output clusters around launch dates", "webinars include a Q&A segment in the final third"],
7
  "summary": "A product-focused collection of 12 videos spanning tutorials, demos, webinars, and interviews. Content centers on onboarding and feature adoption, with tutorial output concentrated around launch cycles."
8
}

Variations

Adapt the analysis by changing the prompt or adding the instructions parameter.

• Target a domain: Add the instructions parameter, such as “You are a media analyst”, to shape the overview for a specific audience.
• Compare collections: Change the prompt to “How do these videos and images compare to a typical corporate training library?”
• Find gaps: Change the prompt to “What topics are underrepresented in these videos and images?”

Jupyter notebook

See also

• Organize a video library - uses a corpus overview as the first step in a full workflow
• Structured output - more on JSON Schema responses
• Create a response - API reference for the Responses endpoint