> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Migrate from Pegasus 1.5 to Pegasus 1.6

> Migrate your application from Pegasus 1.5 to Pegasus 1.6.

To migrate to Pegasus 1.6, change the model name. Everything else in your requests can stay unchanged.

Pegasus 1.5 remains available. Requests without a model name use Pegasus 1.5.

> **Batch analysis**
>
> If you use batch analysis, keep Pegasus 1.5. Batch analysis does not support Pegasus 1.6.

Pegasus 1.6 adds egocentric video understanding, image analysis, improved entity recognition, improved metadata extraction, in-segment events, and segmentation without a token limit. For the full capability list, see the [Pegasus 1.6](/v1.3/docs/concepts/models/pegasus/pegasus-1-6) page.

# Migration steps

#### Upgrade your SDK

#### Python

Install the latest version of the Python SDK.

**`Python`**

```bash Python
pip install --upgrade twelvelabs
```

#### Node.js

Install the latest version of the Node.js SDK.

**`Node.js`**

```bash Node.js
npm install twelvelabs-js@latest
```

#### Update your analysis calls

Set `model_name` to `"pegasus1.6"`.

#### Python

**Before**:

**`Python`**

```python Python maxLines=12
result = client.analyze(
    model_name="pegasus1.5",
    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
    prompt_v_2=AnalyzePromptV2(
        input_text="<YOUR_PROMPT>",
    ),
)
```

**After**:

**`Python`**

```python Python maxLines=12
result = client.analyze(
    model_name="pegasus1.6",
    video=VideoContext_AssetId(asset_id="<YOUR_ASSET_ID>"),
    prompt_v_2=AnalyzePromptV2(
        input_text="<YOUR_PROMPT>",
    ),
)
```

#### Node.js

**Before**:

**`Node.js`**

```javascript Node.js maxLines=12
const result = await client.analyze({
  modelName: "pegasus1.5",
  video: { type: "asset_id", assetId: "<YOUR_ASSET_ID>" },
  promptV2: {
    inputText: "<YOUR_PROMPT>",
  },
});
```

**After**:

**`Node.js`**

```javascript Node.js maxLines=12
const result = await client.analyze({
  modelName: "pegasus1.6",
  video: { type: "asset_id", assetId: "<YOUR_ASSET_ID>" },
  promptV2: {
    inputText: "<YOUR_PROMPT>",
  },
});
```

#### cURL

**Before**:

**`cURL`**

```shell cURL maxLines=12
curl -X POST https://api.twelvelabs.io/v1.3/analyze \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "pegasus1.5",
    "video": { "type": "asset_id", "asset_id": "<YOUR_ASSET_ID>" },
    "prompt_v2": {
      "input_text": "<YOUR_PROMPT>"
    }
  }'
```

**After**:

**`cURL`**

```shell cURL maxLines=12
curl -X POST https://api.twelvelabs.io/v1.3/analyze \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "pegasus1.6",
    "video": { "type": "asset_id", "asset_id": "<YOUR_ASSET_ID>" },
    "prompt_v2": {
      "input_text": "<YOUR_PROMPT>"
    }
  }'
```

No other request changes are required.

#### Use new Pegasus 1.6 features

The following examples show three of the new capabilities: image analysis, in-segment events, and segmentation without a token limit.

**Analyze images**

Pegasus 1.6 analyzes up to 20 images per request.

#### Python

**`Python`**

```python Python maxLines=12
from twelvelabs.types import AnalyzeImageInput

images = [
    AnalyzeImageInput(name="before", url="<FIRST_IMAGE_URL>"),
    AnalyzeImageInput(name="after", url="<SECOND_IMAGE_URL>"),
]
result = client.analyze(
    model_name="pegasus1.6",
    image=images,
    prompt="Compare <@before> and <@after>. Describe the important differences.",
)
```

#### Node.js

**`Node.js`**

```javascript Node.js maxLines=12
const result = await client.analyze({
  modelName: "pegasus1.6",
  image: [
    { name: "before", url: "<FIRST_IMAGE_URL>" },
    { name: "after", url: "<SECOND_IMAGE_URL>" },
  ],
  prompt: "Compare <@before> and <@after>. Describe the important differences.",
});
```

#### cURL

**`cURL`**

```shell cURL maxLines=12
curl -X POST https://api.twelvelabs.io/v1.3/analyze \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "pegasus1.6",
    "image": [
      { "name": "before", "url": "<FIRST_IMAGE_URL>" },
      { "name": "after", "url": "<SECOND_IMAGE_URL>" }
    ],
    "prompt": "Compare <@before> and <@after>. Describe the important differences."
  }'
```

> **Note**
>
> The `image` parameter is mutually exclusive with the `video` and `prompt_v2` parameters. The `prompt` parameter is required when you provide images.

For the complete instructions and examples, see the [Analyze images](/v1.3/docs/guides/analyze-videos-and-images/images) guide.

**Extract in-segment events**

Use `time_array` to extract a list of timestamped events inside each segment. For example, segment a video into scenes and return the start and end time of each spoken line.

#### Python

**`Python`**

```python Python maxLines=12
from twelvelabs.types import AsyncResponseFormat, VideoContext_Url

task = client.analyze_async.tasks.create(
    model_name="pegasus1.6",
    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
    analysis_mode="time_based_metadata",
    response_format=AsyncResponseFormat(
        type="segment_definitions",
        segment_time_format="hh:mm:ss",
        segment_definitions=[
            {
                "id": "scenes",
                "description": "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
                "fields": [
                    {"name": "label", "type": "string", "description": "A short label for this scene"},
                    {
                        "name": "dialogue",
                        "type": "time_array",
                        "description": "The spoken lines of dialogue in this scene",
                        "items": {
                            "type": "object",
                            "fields": [
                                {"name": "speaker", "type": "string", "description": "The name of the person speaking"},
                                {"name": "line", "type": "string", "description": "What the speaker says"},
                            ],
                        },
                    },
                ],
            },
        ],
    ),
)
```

#### Node.js

**`Node.js`**

```javascript Node.js maxLines=12
const { taskId } = await client.analyzeAsync.tasks.create({
  modelName: "pegasus1.6",
  video: { type: "url", url: "<YOUR_VIDEO_URL>" },
  analysisMode: "time_based_metadata",
  responseFormat: {
    type: "segment_definitions",
    segmentTimeFormat: "hh:mm:ss",
    segmentDefinitions: [
      {
        id: "scenes",
        description: "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
        fields: [
          { name: "label", type: "string", description: "A short label for this scene" },
          {
            name: "dialogue",
            type: "time_array",
            description: "The spoken lines of dialogue in this scene",
            items: {
              type: "object",
              fields: [
                { name: "speaker", type: "string", description: "The name of the person speaking" },
                { name: "line", type: "string", description: "What the speaker says" },
              ],
            },
          },
        ],
      },
    ],
  },
});
```

#### cURL

**`cURL`**

```shell cURL maxLines=12
curl -X POST https://api.twelvelabs.io/v1.3/analyze/tasks \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "pegasus1.6",
    "video": { "type": "url", "url": "<YOUR_VIDEO_URL>" },
    "analysis_mode": "time_based_metadata",
    "response_format": {
      "type": "segment_definitions",
      "segment_time_format": "hh:mm:ss",
      "segment_definitions": [
        {
          "id": "scenes",
          "description": "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
          "fields": [
            { "name": "label", "type": "string", "description": "A short label for this scene" },
            {
              "name": "dialogue",
              "type": "time_array",
              "description": "The spoken lines of dialogue in this scene",
              "items": {
                "type": "object",
                "fields": [
                  { "name": "speaker", "type": "string", "description": "The name of the person speaking" },
                  { "name": "line", "type": "string", "description": "What the speaker says" }
                ]
              }
            }
          ]
        }
      ]
    }
  }'
```

For the complete instructions and examples, see the [Segment videos](/v1.3/docs/guides/segment-videos) guide.

**Segment long videos without a token limit**

Set `max_tokens` to `unlimited` to segment long videos without a token ceiling. The task completes even when the platform cannot extract every segment. The `error` field then states that the results may be incomplete.

#### Python

**`Python`**

```python Python maxLines=12
from twelvelabs.types import AsyncResponseFormat, VideoContext_Url

task = client.analyze_async.tasks.create(
    model_name="pegasus1.6",
    video=VideoContext_Url(url="<YOUR_VIDEO_URL>"),
    analysis_mode="time_based_metadata",
    max_tokens="unlimited",
    response_format=AsyncResponseFormat(
        type="segment_definitions",
        segment_time_format="hh:mm:ss",
        segment_definitions=[
            {
                "id": "scenes",
                "description": "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
                "fields": [
                    {"name": "label", "type": "string", "description": "A short label for this scene"},
                    {
                        "name": "dialogue",
                        "type": "time_array",
                        "description": "The spoken lines of dialogue in this scene",
                        "items": {
                            "type": "object",
                            "fields": [
                                {"name": "speaker", "type": "string", "description": "The name of the person speaking"},
                                {"name": "line", "type": "string", "description": "What the speaker says"},
                            ],
                        },
                    },
                ],
            },
        ],
    ),
)
```

#### Node.js

**`Node.js`**

```javascript Node.js maxLines=12
const { taskId } = await client.analyzeAsync.tasks.create({
  modelName: "pegasus1.6",
  video: { type: "url", url: "<YOUR_VIDEO_URL>" },
  analysisMode: "time_based_metadata",
  maxTokens: "unlimited",
  responseFormat: {
    type: "segment_definitions",
    segmentTimeFormat: "hh:mm:ss",
    segmentDefinitions: [
      {
        id: "scenes",
        description: "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
        fields: [
          { name: "label", type: "string", description: "A short label for this scene" },
          {
            name: "dialogue",
            type: "time_array",
            description: "The spoken lines of dialogue in this scene",
            items: {
              type: "object",
              fields: [
                { name: "speaker", type: "string", description: "The name of the person speaking" },
                { name: "line", type: "string", description: "What the speaker says" },
              ],
            },
          },
        ],
      },
    ],
  },
});
```

#### cURL

**`cURL`**

```shell cURL maxLines=12
curl -X POST https://api.twelvelabs.io/v1.3/analyze/tasks \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "pegasus1.6",
    "video": { "type": "url", "url": "<YOUR_VIDEO_URL>" },
    "analysis_mode": "time_based_metadata",
    "max_tokens": "unlimited",
    "response_format": {
      "type": "segment_definitions",
      "segment_time_format": "hh:mm:ss",
      "segment_definitions": [
        {
          "id": "scenes",
          "description": "Segment the video into distinct scenes; within each scene, identify each spoken line of dialogue",
          "fields": [
            { "name": "label", "type": "string", "description": "A short label for this scene" },
            {
              "name": "dialogue",
              "type": "time_array",
              "description": "The spoken lines of dialogue in this scene",
              "items": {
                "type": "object",
                "fields": [
                  { "name": "speaker", "type": "string", "description": "The name of the person speaking" },
                  { "name": "line", "type": "string", "description": "What the speaker says" }
                ]
              }
            }
          ]
        }
      ]
    }
  }'
```

# Additional resources

#### [Analyze videos and images](/v1.3/docs/guides/analyze-videos-and-images)

#### [Segment videos](/v1.3/docs/guides/segment-videos)

#### [Pegasus 1.6](/v1.3/docs/concepts/models/pegasus/pegasus-1-6)

#### [Python SDK Reference](/v1.3/sdk-reference/python/analyze-videos)

#### [Node.js SDK Reference](/v1.3/sdk-reference/node-js/analyze-videos)

#### [API Reference](/v1.3/api-reference/analyze-videos)