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.

TwelveLabs removed Pegasus 1.2 on August 18, 2026. The platform now rejects any request that specifies Pegasus 1.2, and uses Pegasus 1.5 by default when you omit the model_name parameter.

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 code. See the Update your structured responses section for details.

Migration steps

Upgrade your SDK

Python

Node.js

Install the latest version of the Python SDK.

Python

$ pip install --upgrade twelvelabs

Update how you provide the video

Skip this step if you already provide your video as an asset, URL, or base64 string.

If you use sync analysis, upload your video as an asset and provide the unique identifier of that asset instead. If you use async analysis, no changes are needed.

Pegasus 1.5 doesn’t accept the unique identifier of a video you uploaded with a video indexing task. For a step-by-step guide, see Analyze videos.

Python

Node.js

cURL

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

Before:

Python

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

After:

Python

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

If you uploaded your video with the Create a video indexing task method, call the Retrieve video information method. The response includes the unique identifier of your asset.

Update your structured responses

Skip this step if you do not use structured responses.

Structured responses now use separate types for synchronous and asynchronous analysis.

The examples below show the change for synchronous analysis. For asynchronous analysis, make the same change with the asynchronous type.

Python

Node.js

Replace the ResponseFormat type with the SyncResponseFormat type.

Before:

Python

1 from twelvelabs.types import ResponseFormat
2 
3 result = 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

1 from twelvelabs.types import SyncResponseFormat
2 
3 result = 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 )

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

Set the model_name parameter to "pegasus1.5".
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

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

After:

Python

1 from twelvelabs.types import AnalyzePromptV2
2 
3 result = 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.

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

1 from twelvelabs.types import (
2     VideoContext_Url,
3     AsyncResponseFormat,
4     SegmentDefinition,
5     SegmentField,
6 )
7 
8 task = 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 by adding time ranges to individual segment definitions. The following example limits scene detection to two windows (0-30s and 60-90s):

Python

1 from twelvelabs.types import (
2     VideoContext_Url,
3     AsyncResponseFormat,
4     SegmentDefinition,
5     AnalyzeTimeRange,
6 )
7 
8 task = 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. Use <@name> placeholders in the prompt text and provide the referenced images. The following example asks whether a reference photo matches a person in the video:

Python

Node.js

cURL

Python

1 from twelvelabs.types import AnalyzePromptV2, SmeMediaSource, VideoContext_Url
2 
3 result = 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 by setting a start and end time. The clip must be at least 4 seconds long. The following example analyzes a 60-second clip starting at timestamp 30:

Python

Node.js

cURL

Python

1 from twelvelabs.types import AnalyzePromptV2, VideoContext_Url
2 
3 result = 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