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.
• Knowledge store ID: The knowledge_store_id field tells Jockey which knowledge store to reason over. Every request requires exactly one knowledge store ID.

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 to a knowledge store 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 with knowledge_store_id.

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
        "knowledge_store_id": "your_store_id"
15
    }
16
)
17
18
result = response.json()
19
for output in result["output"]:
20
    if output["type"] == "message":
21
        for content in output["content"]:
22
            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
        "knowledge_store_id": "your_store_id"
11
    }
12
)

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
        "knowledge_store_id": "your_store_id",
10
        "include": ["intermediate_outputs"]
11
    }
12
)

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.
• Knowledge store ID required. Every request must include a knowledge_store_id field.
• 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