Request structured JSON responses when you analyze video content. This feature returns predictable, machine-readable data that integrates directly into your applications.

Key features:

• Control response structure: Define exactly how you want your video analysis results formatted using JSON schemas.
• Process responses programmatically: Eliminate manual parsing by receiving data in predictable, machine-readable formats.
• Validate data automatically: Ensure response fields meet your requirements with built-in type and format validation.
• Stream structured content: Retrieve real-time JSON responses as analysis progresses without waiting for completion.
• Integrate seamlessly: Connect video analysis directly into your existing data pipelines and applications.

Use cases:

• Directly populate data into databases: Store video analysis results in structured tables without manual formatting.
• Create automated reports: Generate consistent video summaries and insights for business intelligence dashboards.
• Build content recommendation systems: Extract keywords and topics to power personalized content suggestions.
• Populate content management systems: Auto-generate video titles, descriptions, and tags in your CMS workflow.
• Facilitate search and filtering: Organize video metadata to make content discoverable across your platform

Control responses

Use prompts and schemas together to control your responses:

• The prompt specifies what the platform must extract from the video.
• The schema defines the structure, field names, and data types for the response.

The schema takes precedence over the prompt. If your prompt requests a summary but your schema defines chapters, the platform returns chapters. Always ensure your prompt and schema align to request the same type of information.

Choose your schema

A schema defines:

• Field names: The properties that appear in the JSON response.
• Data types: The type of each field (example: string, number, or object).
• Required fields: Fields that must be present in every response.
• Nested structures: Complex data using object definitions and references.

For complete specifications, see the JSON schema requirements section.

Prerequisites

• You already know how to analyze videos and generate text based on their content, and you’ve already indexed at least one video. For instructions, see the Analyze videos page.

Examples

The examples in this section show different types of structured responses you can request.

1
import json
2
from twelvelabs import TwelveLabs
3
from twelvelabs.types import ResponseFormat
4
5
text = client.analyze(
6
    video_id="<YOUR_VIDEO_ID>",
7
    prompt="Provide a comprehensive summary of this video.",
8
    response_format=ResponseFormat(
9
        json_schema={
10
            "type": "object",
11
            "properties": {
12
                "summary": {"type": "string"}
13
            },
14
            "required": ["summary"],
15
        },
16
    ),
17
)
18
19
data = json.loads(text.data) if text.data else {}
20
print(f"\n{data.get('summary', 'N/A')}\n")
21
print(f"\nFinish Reason: {text.finish_reason}")

Stream structured responses

You can receive structured JSON responses in real-time as they are generated:

1
from twelvelabs import TwelveLabs
2
from twelvelabs.types import ResponseFormat, StreamAnalyzeResponse_StreamEnd
3
4
text_stream = client.analyze_stream(
5
    video_id="<YOUR_VIDEO_ID>",
6
    prompt="<YOUR_PROMPT>",
7
    response_format=ResponseFormat(
8
        type="json_schema",
9
        json_schema={
10
            "type": "object",
11
            "properties": {
12
                "title": {"type": "string"},
13
                "summary": {"type": "string"},
14
                "keywords": {"type": "array", "items": {"type": "string"}},
15
            },
16
        },
17
    ),
18
)
19
for chunk in text_stream:
20
    if chunk.event_type == "text_generation":
21
        print(chunk.text, end="", flush=True)
22
    elif isinstance(chunk, StreamAnalyzeResponse_StreamEnd):
23
        print(f"\nFinish reason: {chunk.finish_reason}")
24
        if chunk.metadata and chunk.metadata.usage:
25
            print(f"Usage: {chunk.metadata.usage}")

Best practices

• Start with simple schemas: Begin with basic object structures and add complexity only when needed.
• Keep schema fields focused and related: Schemas with unrelated fields may require multiple API calls to generate complete results. Group related analysis tasks together or make separate calls for different types of analyses.
• Keep field names descriptive: Use clear, consistent naming conventions for schema properties to make your code more maintainable.
• Mark essential fields as required: Use the required property to specify fields that must be present. This ensures critical data is always included in responses.
• Handle truncated responses: For open-ended analysis, always check the finish_reason field in your code. When it equals length, use the max_tokens parameter to request shorter content, and implement retry logic to avoid incomplete JSON.
• Validate responses client-side: Parse and validate the JSON response in your application to catch any formatting issues before processing the data.
• Test schemas thoroughly: Validate your schema with sample data before deploying to production. Use different video types and content lengths to ensure reliability.

Troubleshooting

This section provides solutions to common issues you might encounter when working with structured JSON responses.

Prompt and response mismatch

Problem: The response contains information different from what you requested in the prompt (for example, you asked for a summary but received chapters).

Cause: The schema takes precedence over the prompt. The platform generates content that matches the schema structure, regardless of what the prompt requests.

Solution: Ensure your prompt and schema align to request the same type of information.

Incomplete or invalid JSON

Problem: The response contains truncated JSON or fails to parse.

Cause: The response reached the token limit before completing the JSON structure.

Solution: Check the finish_reason field. When it equals length, the response was truncated. Increase the max_tokens parameter (the maximum is 4096), simplify your schema by removing optional fields, or make your prompt more concise. For complex requests, break them into multiple API calls.

Invalid schema error

Problem: You receive a BadRequestError with code response_format_invalid when making a request.

Cause: The schema contains unsupported constraints (such as minLength or maxLength) or invalid references (such as $ref pointing to non-existent definitions).

Solution: Review the json_schema field in the API Reference section for a list of the supported constraints. Ensure all $ref values point to definitions in $defs. Remove unsupported validation keywords and use only the supported data types and constraints.

JSON schema requirements

Your schema must adhere to the JSON Schema Draft 2020-12 specification and must meet the requirements below:

• Supported data types: array, boolean, integer, null, number, object, and string.
• Schema constraints: Use validation keywords like pattern for strings, minimum and maximum for integers, required for objects, and minItems for arrays (accepts only 0 or 1).
• Schema composition: You can only use anyOf for combining schemas.
• References: Define subschemas in $defs and reference them with valid $ref URIs pointing to internal subschemas.

For complete schema specifications, see the json_schema field in the API Reference section.