Create a response

Generate responses from your video collection through a single API endpoint. Use this guide to generate your first response from a knowledge store, understand the request and response format before moving to advanced features, and customize Jockey’s behavior for a specific domain.

Key concepts

• Knowledge store: A persistent store of your videos plus the understanding the platform derives from them - entities, moments, relationships, and embeddings. All guides in this section assume you have a knowledge store with at least one item in ready status.
• Response: The object returned by POST /responses. Contains the generated text, a session ID for follow-up turns, and token usage.
• Instructions: A system-level prompt that shapes Jockey’s behavior for a specific domain or task. Same model, same endpoint - different results depending on the instructions you provide.
• Tools: The tools array tells Jockey which knowledge store to reason over. Every request requires exactly one knowledge_store entry.

Prerequisites

• You’ve already uploaded your content, and the asset has reached the ready status. See the Upload content page for details.
• You’ve already created a knowledge store. See the Create a knowledge store page for details.
• You’ve already added at least one asset to the knowledge store, and the item has reached the ready status. See the Add assets page for details.

Basic usage

Every interaction with Jockey goes through POST /responses. Provide a natural-language message in the input array and specify the knowledge store to reason over in tools.

1
import requests
2
3
HEADERS = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}
4
BASE_URL = "https://api.twelvelabs.io/v1.3"
5
6
response = requests.post(
7
    f"{BASE_URL}/responses",
8
    headers=HEADERS,
9
    json={
10
        "model": "jockey1.0",
11
        "input": [
12
            {"type": "message", "role": "user", "content": "What are the main themes across these videos?"}
13
        ],
14
        "tools": [
15
            {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
16
        ]
17
    }
18
)
19
20
result = response.json()
21
for output in result["output"]:
22
    if output["type"] == "message":
23
        for content in output["content"]:
24
            print(content["text"])

The response contains a session_id you can use for follow-up turns (see Multi-turn sessions), an output array with the generated content, and a usage object with token counts:

1
{
2
  "id": "resp_abc123",
3
  "session_id": "sess_xyz789",
4
  "status": "completed",
5
  "output": [
6
    {
7
      "type": "message",
8
      "content": [{"type": "output_text", "text": "The main themes across your videos include..."}]
9
    }
10
  ],
11
  "usage": {"input_tokens": 1250, "output_tokens": 340}
12
}

Customize behavior with instructions

The instructions field is a system-level prompt that specializes Jockey for your domain. Same API, same model - different behavior depending on what you provide.

1
response = requests.post(
2
    f"{BASE_URL}/responses",
3
    headers=HEADERS,
4
    json={
5
        "model": "jockey1.0",
6
        "instructions": "You are a sports analyst. Focus on player performance, tactics, and key moments.",
7
        "input": [
8
            {"type": "message", "role": "user", "content": "Summarize the key plays from this game"}
9
        ],
10
        "tools": [
11
            {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
12
        ]
13
    }
14
)

Swap instructions to reshape Jockey for different contexts:

Read the response

The response object contains metadata, the generated content, and token usage. Use the fields below to extract what you need.

1
result = response.json()
2
3
# Response metadata
4
print(f"ID: {result['id']}")
5
print(f"Session: {result['session_id']}")
6
print(f"Status: {result['status']}")
7
8
# Token usage - tracks input and output tokens for this request
9
print(f"Tokens: {result['usage']}")
10
11
# Output content - iterate through the output array to find message blocks
12
for output in result["output"]:
13
    if output["type"] == "message":
14
        for content in output["content"]:
15
            print(content["text"])

Inspect intermediate outputs

Jockey performs multi-step reasoning internally - searching, analyzing, and synthesizing across your videos. Add "intermediate_outputs" to the include array to see these reasoning steps alongside the final answer. This is useful for debugging or understanding how Jockey arrived at a conclusion.

1
response = requests.post(
2
    f"{BASE_URL}/responses",
3
    headers=HEADERS,
4
    json={
5
        "model": "jockey1.0",
6
        "input": [
7
            {"type": "message", "role": "user", "content": "What are the main themes?"}
8
        ],
9
        "tools": [
10
            {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
11
        ],
12
        "include": ["intermediate_outputs"]
13
    }
14
)

What you can do

The Responses API handles a wide range of tasks through the same endpoint. These examples are illustrative, not exhaustive.

For complete runnable code, see Recipes.

Common pitfalls

• Knowledge store must have ready items. If no items are ready, the response has nothing to reason over.
• Exactly one tool required. The tools array must contain exactly one knowledge_store entry.
• Input format matters. Each message needs type, role, and content fields.

Next steps

• Streaming - receive tokens in real time instead of waiting for the full response
• Structured output - get typed JSON back by providing a schema
• Multi-turn sessions - maintain conversation context across requests

Jupyter notebook

Download the notebook to run this guide interactively.

API reference

• POST /responses