> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Enrich content

> Apply a domain-specific lens to produce richer, more targeted analysis of your videos and images.

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](/v1.3/agents/guides/create-a-response/structured-output) page.

# Workflow

This recipe combines three elements: a JSON schema that defines the enrichment data structure, instructions that give [Jockey](/v1.3/agents/concepts/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 [Create a knowledge store](/v1.3/agents/guides/create-a-knowledge-store) and [Add assets to a knowledge store](/v1.3/agents/guides/add-assets) guides for details.
* You're familiar with the request and response format. See the [Create a response](/v1.3/agents/guides/create-a-response) page for details.

# Complete example

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

**`Python`**

```python Python maxlines=38
import json
from twelvelabs import TwelveLabs, TextParam
from twelvelabs.types.text_param_format import TextParamFormat_JsonSchema

client = TwelveLabs(api_key="<YOUR_API_KEY>")
STORE_ID = "<YOUR_KNOWLEDGE_STORE_ID>"

# Define a JSON schema for the enrichment results
enrichment_schema = {
    "type": "object",
    "properties": {
        "enrichments": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "item_reference": {"type": "string", "description": "The plain UUID of the source item"},  # Source item identifier
                    "original_summary": {"type": "string"},    # Default summary from indexing
                    "enriched_analysis": {"type": "string"},   # Domain-specific analysis
                    "new_insights": {"type": "array", "items": {"type": "string"}},  # Domain-specific findings
                    "tags": {"type": "array", "items": {"type": "string"}},           # Domain-specific labels
                },
            },
        }
    },
}

# Run the enrichment
response = client.responses.create(
    knowledge_store_id=STORE_ID,
    instructions="You are a brand strategist. Analyze videos through the lens of brand perception and marketing effectiveness.",
    input=[{"type": "message", "role": "user", "content": "For each video, provide enriched analysis focusing on brand messaging effectiveness, audience engagement signals, and production quality."}],
    text=TextParam(format=TextParamFormat_JsonSchema(name="content_enrichment", schema_=enrichment_schema)),
)

# Parse and read the enrichments
for output in response.output:
    if output.type == "message":
        for content in output.content:
            data = json.loads(content.text)
            for e in data["enrichments"]:
                print(f"\n{e['item_reference']}")
                print(f"  Analysis: {e['enriched_analysis']}")
                print(f"  Insights: {', '.join(e['new_insights'])}")
                print(f"  Tags: {', '.join(e['tags'])}")
```

**`Node.js`**

```javascript Node.js maxlines=38
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });
const storeId = "<YOUR_KNOWLEDGE_STORE_ID>";

// Define a JSON schema for the enrichment results
const enrichmentSchema = {
  type: "object",
  properties: {
    enrichments: {
      type: "array",
      items: {
        type: "object",
        properties: {
          item_reference: { type: "string", description: "The plain UUID of the source item" }, // Source item identifier
          original_summary: { type: "string" }, // Default summary from indexing
          enriched_analysis: { type: "string" }, // Domain-specific analysis
          new_insights: { type: "array", items: { type: "string" } }, // Domain-specific findings
          tags: { type: "array", items: { type: "string" } }, // Domain-specific labels
        },
      },
    },
  },
};

// Run the enrichment
const response = await client.responses.create({
  knowledgeStoreId: storeId,
  instructions: "You are a brand strategist. Analyze videos through the lens of brand perception and marketing effectiveness.",
  input: [{ type: "message", role: "user", content: "For each video, provide enriched analysis focusing on brand messaging effectiveness, audience engagement signals, and production quality." }],
  text: { format: { type: "json_schema", name: "content_enrichment", schema: enrichmentSchema } },
});

// Parse and read the enrichments
for (const output of response.output ?? []) {
  if (output.type === "message") {
    for (const content of output.content ?? []) {
      const data = JSON.parse(content.text);
      for (const e of data.enrichments) {
        console.log(`\n${e.item_reference}`);
        console.log(`  Analysis: ${e.enriched_analysis}`);
        console.log(`  Insights: ${e.new_insights.join(", ")}`);
        console.log(`  Tags: ${e.tags.join(", ")}`);
      }
    }
  }
}
```

# Code explanation

#### Python

To enrich your content through a domain lens, call the [`responses.create`](/v1.3/sdk-reference/python/responses#create-a-response) 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. Within it, the `schema_` field defines the structure the output must match, and the `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](/v1.3/agents/guides/create-a-response/structured-output#json-schema-requirements) 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 the `json.loads()` method, then iterate the `enrichments` array to read the analysis of each video.
* `usage`: Token usage statistics, including the `input_tokens` and `output_tokens` fields.

#### Node.js

To enrich your content through a domain lens, call the [`responses.create`](/v1.3/sdk-reference/node-js/responses#create-a-response) method with domain `instructions`, a prompt, and a `text` parameter that describes your result schema. You pass all parameters as properties of a single object.\

**Parameters**:

* `knowledgeStoreId`: 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. Within it, the `type` field must be `"json_schema"`, the `schema` field defines the structure the output must match, and the `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](/v1.3/agents/guides/create-a-response/structured-output#json-schema-requirements) page.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `ResponseObject` containing, among other information, the following fields:

* `id`: The unique identifier of the response.
* `knowledgeStoreId`: The knowledge store this response was generated against.
* `sessionId`: 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 the `JSON.parse()` method, then iterate the `enrichments` array to read the analysis of each video.
* `usage`: Token usage statistics, including the `inputTokens` and `outputTokens` 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:

```json
{
  "enrichments": [
    {
      "item_reference": "069eb4e8-aeb0-7e83-8000-86413fcc296a",
      "original_summary": "A 3-minute product launch video featuring a presenter demonstrating a new smartwatch with outdoor activity footage.",
      "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.",
      "new_insights": [
        "Strong brand-lifestyle alignment through outdoor activity sequences",
        "Product features presented in context of real-world use rather than specifications",
        "Call-to-action placement at 2:30 follows the engagement peak"
      ],
      "tags": ["brand_lifestyle", "product_demo", "aspirational_messaging", "strong_pacing"]
    }
  ]
}
```

> **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.

# Jupyter notebook

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/recipes/enrich_content.ipynb)

# See also

* [Structured output](/v1.3/agents/guides/create-a-response/structured-output) - more on JSON Schema responses
* [Configure ingestion](/v1.3/agents/guides/create-a-knowledge-store/configure-ingestion) - configure extraction at index time instead of at response time
* [Create a response](/v1.3/api-reference/responses/create) - API reference for the Responses endpoint