TwelveLabs offers two ways to work with your videos and images, both built on the same ingestion flow.

Models: Dedicated APIs for individual tasks. Search for moments across your videos, analyze a video, or generate embeddings, then combine the results yourself.
Agents: Jockey, a unified agentic system that reasons across your videos and images. Ask a question, and Jockey plans its own steps, runs them, and returns a grounded, cited answer.
Use both together: Combine Models for embeddings and per-video analysis with Jockey for corpus-level reasoning.

This guide compares the two, helps you evaluate which workflows to migrate, and walks through a search workflow migration step by step.

Key differences

The following table highlights the key differences between Models and Agents.

Models	Agents	Difference
Index	Knowledge store	A knowledge store contains your videos and images plus derived understanding - entities, relationships, and embeddings - not just a vector index.
Indexed video	Asset + knowledge store item	Upload creates an asset (a video or an image). Adding it to a knowledge store creates an item. One asset can exist in multiple knowledge stores.
Marengo / Pegasus	Jockey	You no longer choose a model. Jockey plans and runs the necessary steps across all modalities itself.
`POST /search`	`POST /knowledge-stores/{id}/search` or `POST /responses`	Knowledge store search returns ranked matches directly; the Responses API adds agentic reasoning and explanations. Both take natural language.
Search options (for example, `visual` and `audio`)	Automatic with Jockey; optional on search	The Responses API needs no modality configuration; Jockey selects the modalities itself. Knowledge store search accepts the `search_options` parameter and matches on visual content by default.
`POST /embed`	No equivalent	Continue using the Embed API for vector embeddings.

Detailed comparison by task

The following table shows which tasks each API supports.

Task	Models	Agents
Search for moments in videos	✅ Search API	✅ Knowledge store search (or Responses API for agentic search)
Summarize a single video	✅ Analyze API	✅ Responses API (target one item with `selections`)
Organize videos by topic	❌	✅ Responses API with structured output
Track entities across videos	❌	✅ Responses API
Build agent workflows	❌	✅ Multi-turn sessions + structured output
Generate vector embeddings	✅ Embed API	❌

Agents return text, data references, and timestamps, not processed video. Use these references in your own rendering pipeline.

When you scope a request to specific items with selections, Jockey treats them as a strong preference, not a hard boundary. It can still draw on other items in the knowledge store. For strict single-video analysis, keep the Analyze API.

Choose the workflows to migrate

Some workflows can move to Agents. Others should stay on the existing Models APIs.

Current workflow	Recommendation	Reason
Search for moments in videos	Use knowledge store search for a direct match, or the Responses API for agentic search.	Knowledge store search returns ranked matches directly. The Responses API adds cross-video reasoning, multi-turn refinement, and structured output.
Analyze a single video for summaries or Q&A	Keep the Analyze API, or use the Responses API with `selections`.	The Analyze API handles stateless, single-video analysis. Targeting one item with `selections` in the Responses API adds reasoning, multi-turn refinement, and structured output.
Generate embeddings for machine-learning pipelines	Keep using the Embed API.	Agents do not generate vector embeddings.

TwelveLabs recommends you start with a pilot. Upload a subset of your existing content to a pilot knowledge store. Compare results side by side before migrating production workflows.

Migrate a search workflow

This example shows how to move a search workflow from Models to Agents. Both approaches start by uploading a video as an asset. The differences begin after upload.

Step	Models	Agents
1. Upload an asset	Upload a video file or URL	Same
2. Create a container	Create an index with model and modality configuration	Create a knowledge store (no model configuration needed)
3. Add the asset	Add to index, poll until indexed	Add to knowledge store, poll until indexed
4. Query	`POST /search` with structured parameters	`POST /responses` (agentic) or `POST /knowledge-stores/{id}/search`, both with natural language

What you gain:

No model selection: Jockey processes all modalities automatically
Natural language queries: describe what you want instead of specifying search options
Follow-up queries: refine results in a multi-turn session
Corpus-level reasoning: generate responses that reason across your entire video and image collection
Structured output: retrieve typed JSON responses using a schema

For a working code example of the Agents workflow, see the Quickstart.

Research preview limitations

During the research preview period:

Webhooks are not available. Use polling to check processing status
Rate limits may differ from Models
The API surface may change before general availability
SLAs do not apply

Models continue to operate. Adopt Agents at your own pace.

Next steps

Guides - set up content, configure ingestion, and generate responses
Recipes - common tasks you can adapt to your use case