For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • Get Started
    • Introduction
    • Quickstart
    • Manage your plan
    • Rate limits
    • Release notes
    • Migration guide
  • Guides
    • Search
    • Analyze videos
    • Segment videos
    • Create embeddings
  • Concepts
    • Models
    • Upload and processing methods
    • Indexes
    • Modalities
    • Multimodal large language models
  • Cloud partner integrations
    • Amazon Bedrock
  • Advanced
    • Organizations
    • Fine-tuning
    • Webhooks
    • Metadata
    • Model context protocol
    • Claude Code Plugin
  • Resources
    • Platform overview
    • Playground
    • TwelveLabs SDKs
    • Frequently asked questions
    • Use cases
    • Sample applications
    • Partner integrations
    • From the community
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
On this page
  • Migration steps
  • Additional resources
Get Started

Migrate from Pegasus 1.2 to Pegasus 1.5

Was this page helpful?
Previous

Guides

Next
Built with

This guide shows how to migrate your application to Pegasus 1.5. It focuses on SDK migrations, but it also includes cURL examples for steps where the request shape changes.

Pegasus 1.5 adds the following capabilities over Pegasus 1.2:

  • Video segmentation with structured, timestamped output, including per-definition time ranges
  • Structured prompts with up to 4 reference images
  • Video clipping to analyze specific time ranges
  • Responses up to 65,536 tokens (up from 4,096)

Pegasus 1.2 remains available for general analysis only.

To use Pegasus 1.5, update your SDK to the latest version, or update your REST API calls as shown in the cURL examples. If you use structured responses, you may also need to update your response format types. See the Update the ResponseFormat type section for details.

Migration steps

1

Upgrade your SDK

Python
Node.js

Install the latest version of the Python SDK.

Python
$pip install --upgrade twelvelabs
2

Replace video_id with the video parameter

Skip this step if you already use the video parameter.

Pegasus 1.5 no longer supports the video_id parameter. If you use sync analysis, upload your video as an asset and pass the asset ID through the video parameter instead. The async analysis endpoint already requires the video parameter, so no changes are needed. For a complete walkthrough, see the Analyze videos guide.

Python
Node.js
cURL

Replace the video_id parameter with a VideoContext_AssetId object passed to the video parameter.

Before:

Python
1result = client.analyze(
2    video_id="<YOUR_VIDEO_ID>",
3    prompt="<YOUR_PROMPT>",
4)

After:

Python
1from twelvelabs.types import VideoContext_AssetId
2
3result = client.analyze(
4    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
5    prompt="<YOUR_PROMPT>",
6)

To find the asset ID for a video you uploaded with the Create a video indexing task method, call the Retrieve video information method. The response includes the asset_id field.

3

Update the ResponseFormat type

Skip this step if you do not use structured responses.

The ResponseFormat type has been split into SyncResponseFormat for synchronous analysis and AsyncResponseFormat for asynchronous analysis.

The examples below show how to update your code for sync analysis. For async analysis, make similar changes and replace ResponseFormat with AsyncResponseFormat.

Python
Node.js

Replace ResponseFormat with SyncResponseFormat.

Before:

Python
1from twelvelabs.types import ResponseFormat
2
3result = client.analyze(
4    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
5    prompt="<YOUR_PROMPT>",
6    response_format=ResponseFormat(
7        type="json_schema",
8        json_schema={"type": "object", "properties": {"summary": {"type": "string"}}},
9    ),
10)

After:

Python
1from twelvelabs.types import SyncResponseFormat
2
3result = client.analyze(
4    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
5    prompt="<YOUR_PROMPT>",
6    response_format=SyncResponseFormat(
7        type="json_schema",
8        json_schema={"type": "object", "properties": {"summary": {"type": "string"}}},
9    ),
10)
4

Update your analysis calls

These changes apply to both sync and async methods. The examples below show how to update your code for sync analysis. For async analysis, make similar changes.

Python
Node.js
cURL
  • Add the optional model_name parameter and set it to "pegasus1.5". If you omit this parameter, the platform uses Pegasus 1.2 by default.
  • Replace the prompt parameter with prompt_v_2. This parameter is now an object. Set the input_text field to your prompt text.
Note
You can still use the prompt parameter, but it will be deprecated in a future version. TwelveLabs recommends that you replace it with prompt_v_2.

Before:

Python
1result = client.analyze(
2    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
3    prompt="<YOUR_PROMPT>",
4)

After:

Python
1from twelvelabs.types import AnalyzePromptV2
2
3result = client.analyze(
4    model_name="pegasus1.5",
5    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
6    prompt_v_2=AnalyzePromptV2(
7        input_text="<YOUR_PROMPT>",
8    ),
9)
Note
Pegasus 1.5 supports up to 65,536 tokens, compared to 4,096 for Pegasus 1.2. If your application validates or caps max_tokens, update the limit.
5

Use new Pegasus 1.5 features

The following examples show each new capability.

Video segmentation

Pegasus 1.5 transforms raw videos into structured, timestamped data. Define the types of segments you want to detect and the custom fields you want to extract. Video segmentation requires the asynchronous analysis endpoint.

Python
Node.js
cURL

The following example detects scene changes and extracts a sentiment field for each segment:

Python
1from twelvelabs.types import (
2    VideoContext_Url,
3    AsyncResponseFormat,
4    SegmentDefinition,
5    SegmentField,
6)
7
8task = client.analyze_async.tasks.create(
9    model_name="pegasus1.5",
10    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
11    analysis_mode="time_based_metadata",
12    response_format=AsyncResponseFormat(
13        type="segment_definitions",
14        segment_definitions=[
15            SegmentDefinition(
16                id="scene",
17                description="A distinct scene or setting change in the video",
18                fields=[
19                    SegmentField(
20                        name="sentiment",
21                        type="string",
22                        description="The emotional tone of this segment",
23                        enum=["positive", "negative", "neutral"],
24                    ),
25                ],
26            ),
27        ],
28    ),
29)

You can also restrict segment extraction to specific time windows. Add the time_ranges parameter to individual segment definitions. The following example limits scene detection to two windows (0-30s and 60-90s):

Python
1from twelvelabs.types import (
2    VideoContext_Url,
3    AsyncResponseFormat,
4    SegmentDefinition,
5    AnalyzeTimeRange,
6)
7
8task = client.analyze_async.tasks.create(
9    model_name="pegasus1.5",
10    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
11    analysis_mode="time_based_metadata",
12    response_format=AsyncResponseFormat(
13        type="segment_definitions",
14        segment_definitions=[
15            SegmentDefinition(
16                id="scene",
17                description="A distinct scene or setting change",
18                time_ranges=[
19                    AnalyzeTimeRange(start_time=0.0, end_time=30.0),
20                    AnalyzeTimeRange(start_time=60.0, end_time=90.0),
21                ],
22            ),
23        ],
24    ),
25)

Structured prompts with reference images

Python
Node.js
cURL

Reference up to 4 images in your prompt using prompt_v_2. Use <@name> placeholders in the prompt text and declare the images in media_sources. The following example asks whether a reference photo matches a person in the video:

Python
1from twelvelabs.types import AnalyzePromptV2, SmeMediaSource, VideoContext_Url
2
3result = client.analyze(
4    model_name="pegasus1.5",
5    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
6    prompt_v_2=AnalyzePromptV2(
7        input_text="Does the person in the video resemble <@reference_photo>?",
8        media_sources=[
9            SmeMediaSource(
10                name="reference_photo",
11                media_type="image",
12                url="<YOUR_IMAGE_URL>",
13            ),
14        ],
15    ),
16)

Video clipping

Python
Node.js
cURL

Analyze a specific portion of a video with the start_time and end_time parameters. The clip must be at least 4 seconds long. The following example analyzes a 60-second clip starting at the 30-second mark:

Python
1from twelvelabs.types import AnalyzePromptV2, VideoContext_Url
2
3result = client.analyze(
4    model_name="pegasus1.5",
5    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
6    prompt_v_2=AnalyzePromptV2(
7        input_text="What happens in this clip?",
8    ),
9    start_time=30.0,
10    end_time=90.0,
11)

Additional resources

Analyze videos
Segment videos
Python SDK Reference
Node.js SDK Reference
API Reference