This recipe shows you how to apply a domain-specific lens to your videos and images and receive structured, targeted analysis. The response includes per-item enrichments with domain-specific insights and tags, ready for your content pipeline or metadata system.

Use cases:

Brand analysis: Evaluate brand messaging, audience engagement, and production quality across videos and images
Accessibility audits: Describe visual elements for screen readers, assess caption quality, and identify audio-only content
Compliance reviews: Identify claims, disclaimers, and required disclosures in your content
SEO metadata extraction: Generate keywords, descriptions, titles, and topic clusters from your content

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.
Instructions: Additional guidance that shapes Jockey’s behavior for a specific domain or task.
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 combines three elements: a JSON schema that defines the enrichment data structure, instructions that give Jockey a specific role and domain guidance, and a prompt that describes what analysis you want. Jockey reasons across your knowledge store, finds relevant content, and returns structured results that match your schema. You can adapt this recipe to analyze content through a different domain lens.

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.

Complete 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 enrichment results
9 enrichment_schema = {
10     "type": "object",
11     "properties": {
12         "enrichments": {
13             "type": "array",
14             "items": {
15                 "type": "object",
16                 "properties": {
17                     "item_reference": {"type": "string", "description": "The plain UUID of the source item"},  # Source item identifier
18                     "original_summary": {"type": "string"},    # Default summary from indexing
19                     "enriched_analysis": {"type": "string"},   # Domain-specific analysis
20                     "new_insights": {"type": "array", "items": {"type": "string"}},  # Domain-specific findings
21                     "tags": {"type": "array", "items": {"type": "string"}},           # Domain-specific labels
22                 },
23             },
24         }
25     },
26 }
27 
28 # Run the enrichment
29 response = client.responses.create(
30     knowledge_store_id=STORE_ID,
31     instructions="You are a brand strategist. Analyze videos through the lens of brand perception and marketing effectiveness.",
32     input=[{"type": "message", "role": "user", "content": "For each video, provide enriched analysis focusing on brand messaging effectiveness, audience engagement signals, and production quality."}],
33     text=TextParam(format=TextParamFormat_JsonSchema(name="content_enrichment", schema_=enrichment_schema)),
34 )
35 
36 # Parse and read the enrichments
37 for output in response.output:
38     if output.type == "message":
39         for content in output.content:
40             data = json.loads(content.text)
41             for e in data["enrichments"]:
42                 print(f"\n{e['item_reference']}")
43                 print(f"  Analysis: {e['enriched_analysis']}")
44                 print(f"  Insights: {', '.join(e['new_insights'])}")
45                 print(f"  Tags: {', '.join(e['tags'])}")

Code explanation

Python

Node.js

To enrich your content through a domain lens, call the responses.create method with domain instructions, a prompt, and a text parameter that describes your result schema.
Parameters:

knowledge_store_id: The unique identifier of the knowledge store to reason over.
input: An array of input items. Each item is a message you send to Jockey. This example requests enriched analysis of brand messaging effectiveness, audience engagement signals, and production quality.
instructions: A per-request system prompt that shapes Jockey’s behavior for a domain or task. This example uses a brand strategist role focused on brand perception and marketing effectiveness.
text: An object that specifies the response format. To return structured JSON, set the format field: its schema_ field defines the structure the output must match, and its name field identifies the schema. Design the schema to fit your use case; the inline comments in the example describe each field. For the schema rules, see the Structured output page.

Return value: An object of type ResponseObject containing, among other information, the following fields:

id: The unique identifier of the response.
knowledge_store_id: The knowledge store this response was generated against.
session_id: The session identifier. Pass it in a follow-up request to continue the conversation.
status: The status of the response. The possible values are completed, failed, in_progress, and incomplete.
output: The response output items. The text field of each content part in a message item is a JSON string that matches your schema. Parse it with json.loads(), then iterate the enrichments array to read each video’s analysis.
usage: Token usage statistics, including the input_tokens and output_tokens fields.

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   "enrichments": [
3     {
4       "item_reference": "069eb4e8-aeb0-7e83-8000-86413fcc296a",
5       "original_summary": "A 3-minute product launch video featuring a presenter demonstrating a new smartwatch with outdoor activity footage.",
6       "enriched_analysis": "The video leads with aspirational outdoor imagery before transitioning to product features. Brand messaging emphasizes durability and adventure. The presenter maintains an enthusiastic but credible tone, and quick cuts between lifestyle footage and close-up product shots sustain viewer attention.",
7       "new_insights": [
8         "Strong brand-lifestyle alignment through outdoor activity sequences",
9         "Product features presented in context of real-world use rather than specifications",
10         "Call-to-action placement at 2:30 follows the engagement peak"
11       ],
12       "tags": ["brand_lifestyle", "product_demo", "aspirational_messaging", "strong_pacing"]
13     }
14   ]
15 }

Note

The original_summary field is populated from the summary the platform generated when the video was indexed.

Variations

Change the instructions and prompt to adapt this recipe for different domains and analysis types.

Change the domain lens: Set the instructions parameter to a different analytical perspective. The schema stays the same.
- Accessibility: “Analyze for accessibility: describe visual elements for screen readers, note caption quality, identify audio-only content.”
- Compliance: “Review for regulatory compliance: identify claims, disclaimers, required disclosures.”
- Education: “Analyze pedagogical effectiveness: identify learning objectives, teaching methods, assessment opportunities.”
- SEO: “Extract SEO metadata: keywords, descriptions, suggested titles, topic clusters.”
Run a comparative analysis: Set the instructions to “Enrich by comparing each video to the collection average.”
Find coverage gaps: Ask “What aspects of these videos and images are under-documented?” to identify areas that need deeper analysis.
Target a specific audience: Change the instructions to enrich for different target audiences, such as executives, students, or technical reviewers.

Enrich content