Get Started

Migrate from Pegasus 1.2 to Pegasus 1.5

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 98,304 tokens (up from 4,096) within a shared context window

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

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.

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.

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.

  • 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 responses up to 98,304 tokens, compared to 4,096 for Pegasus 1.2. The input and response must fit within the context window. If your application validates or caps the maximum response length, 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.

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

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

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 timestamp 30:

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