Assemble highlight reels

Find and sequence relevant clips from a video collection based on a theme, topic, or criteria. Returns a list of clip references with timestamps, ready for assembly in your editing tool or pipeline.

What you’ll build

A workflow that searches your video collection for clips matching your criteria, returns structured clip references (video IDs + timestamps), and provides assembly notes for sequencing.

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.

Find and assemble clips

Use instructions to set the editorial perspective and a schema to capture structured clip references. The prompt describes what you want in the highlight reel - Jockey finds the best matching moments and suggests a sequence.

1 import json
2 import requests
3 
4 API_KEY = "YOUR_API_KEY"
5 BASE_URL = "https://api.twelvelabs.io/v1.3"
6 HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
7 STORE_ID = "your_knowledge_store_id"
8 
9 clip_schema = {
10     "type": "object",
11     "properties": {
12         "assembly_title": {"type": "string"},
13         "clips": {
14             "type": "array",
15             "items": {
16                 "type": "object",
17                 "properties": {
18                     "video_reference": {"type": "string"},
19                     "start_time": {"type": "string"},
20                     "end_time": {"type": "string"},
21                     "description": {"type": "string"},
22                     "relevance_reason": {"type": "string"}
23                 }
24             }
25         },
26         "total_estimated_duration": {"type": "string"},
27         "assembly_notes": {"type": "string"}
28     }
29 }
30 
31 response = requests.post(
32     f"{BASE_URL}/responses",
33     headers=HEADERS,
34     json={
35         "model": "jockey1.0",
36         "instructions": "You are a video editor assembling a highlight reel. Select clips that flow well together with good pacing and variety.",
37         "input": [
38             {
39                 "type": "message",
40                 "role": "user",
41                 "content": "Find the best clips showing product demos and customer reactions. I need a 2-minute highlight reel."
42             }
43         ],
44         "tools": [
45             {"type": "knowledge_store", "knowledge_store_id": STORE_ID}
46         ],
47         "text": {"format": "json_schema", "json_schema": clip_schema}
48     }
49 )
50 
51 result = response.json()
52 for output in result["output"]:
53     if output["type"] == "message":
54         for content in output["content"]:
55             assembly = json.loads(content["text"])
56             print(f"Assembly: {assembly['assembly_title']}")
57             print(f"Duration: {assembly['total_estimated_duration']}")
58             for i, clip in enumerate(assembly["clips"], 1):
59                 print(f"  {i}. [{clip['start_time']}-{clip['end_time']}] {clip['description']}")

Example response

A typical response includes clip references with timestamps and editorial context:

1 {
2   "assembly_title": "Product Demo Highlights Q1",
3   "clips": [
4     {
5       "video_reference": "marketing_video_03",
6       "start_time": "00:01:22",
7       "end_time": "00:01:45",
8       "description": "Close-up product walkthrough with feature callouts",
9       "relevance_reason": "Strong visual demonstration of core feature"
10     },
11     {
12       "video_reference": "customer_interview_07",
13       "start_time": "00:03:10",
14       "end_time": "00:03:38",
15       "description": "Customer describing their positive experience",
16       "relevance_reason": "Authentic testimonial with emotional impact"
17     }
18   ],
19   "total_estimated_duration": "1:52",
20   "assembly_notes": "Opens with product demo for context, transitions to customer reactions for social proof"
21 }

Variations

Change the editorial style: Swap instructions to “documentary editor”, “social media creator”, or “training video producer”
Change the content focus: “funny moments”, “technical deep dives”, “executive summaries”
Refine with follow-up turns: Use a multi-turn session to adjust: “Replace the second clip with something more energetic”

Jupyter notebook

Download the notebook to run this recipe interactively.