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

# Analyze videos and images

> Quickstart: analyze videos and images to generate text. Working examples with core parameters.

This quickstart guide provides a simplified introduction to analyzing videos and images to generate text using the TwelveLabs Video Understanding Platform. It includes the following:

* A working example for each method: analyze a video and analyze images
* Minimal implementation details
* Core parameters for common use cases

For comprehensive guides, see the [Analyze videos and images](/v1.3/docs/guides/analyze-videos-and-images) section.

# Key concepts

This section explains the key concepts and terminology used in this guide:

* **Asset**: Your uploaded content. Once created, you can reference the same asset across multiple operations without uploading the file again.

# Workflow

The platform provides two methods to analyze videos and images. Choose the method that fits your use case:

#### [Analyze videos](#analyze-videos)

Upload your video as an asset and analyze it with a prompt. The platform streams the generated text.

#### [Analyze images](#analyze-images)

Upload your images as assets and analyze them with a prompt. The platform streams the generated text.

# Prerequisites

* To use the platform, you need an API key:

  If you don't have an account, [sign up](https://playground.twelvelabs.io/) for a free account.

  Go to the [API Keys](https://playground.twelvelabs.io/dashboard/api-keys) page.

  If you need to create a new key, select the **Create API Key** button. Enter a name and set the expiration period. The default is 12 months.

  Select the **Copy** icon next to your key to copy it to your clipboard.

* Depending on the programming language you are using, install the TwelveLabs SDK by entering one of the following commands:

  **`Python`**

  ```shell Python
  pip install --upgrade twelvelabs
  ```

  **`Node.js`**

  ```shell Node.js
  yarn add twelvelabs-js@latest # or npm install twelvelabs-js@latest
  ```

* Your videos must meet the following requirements:
  * **Upload limits**: Public video URLs up to 4 GB or local videos up to 200 MB. For a video up to 10 GB, use multipart uploads. See the [Upload and processing methods](/v1.3/docs/concepts/upload-methods) page for details.

  * **Analysis method**: Videos from 1 second to 1 hour. For longer videos, use the asynchronous method in the [complete guide](/v1.3/docs/guides/analyze-videos-and-images/videos).

  * **Model capabilities**: See the complete requirements for [videos](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#video-file-requirements)

* Your images must meet the following requirements:
  * **Number of images**: one to twenty per request
  * **Formats**: JPEG, PNG, WebP, GIF, and BMP
  * **File size**: ≤ 20 MB per image
  * **Pixel count**: ≤ 16,777,216 pixels per image (width × height)

# Analyze videos

Upload your video as an asset, then analyze it with a custom prompt. The platform processes your request synchronously and streams the generated text.

## Starter code

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```Python Python maxLines=12
import time
from twelvelabs import TwelveLabs
from twelvelabs.types import VideoContext_AssetId, AnalyzePromptV2

# 1. Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")

# 2. Upload a video
asset = client.assets.create(
    method="url",
    url="<YOUR_VIDEO_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
    # Or use method="direct" and file=open("<PATH_TO_VIDEO_FILE>", "rb") to upload a local file up to 200 MB
)
print(f"Created asset: id={asset.id}")

# 3. Check the status of the asset
print("Waiting for asset to be ready...")
while True:
    asset = client.assets.retrieve(asset.id)
    if asset.status == "ready":
        print("Asset is ready")
        break
    if asset.status == "failed":
        raise RuntimeError(f"Asset processing failed: id={asset.id}")
    time.sleep(5)

# 4. Analyze your video
video = VideoContext_AssetId(asset_id=asset.id)
text_stream = client.analyze_stream(
    model_name="pegasus1.6",
    video=video,
    prompt_v_2=AnalyzePromptV2(
        input_text="<YOUR_PROMPT>",
    ),
)

# 5. Process the results
for text in text_stream:
    if text.event_type == "text_generation":
        print(text.text)
```

**`Node.js`**

```JavaScript Node.js maxLines=12
import { TwelveLabs } from "twelvelabs-js";
// Uncomment the next line if uploading a local file
// import fs from "fs";

// 1. Initialize the client
const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// 2. Upload a video
const asset = await client.assets.create({
  method: "url",
  url: "<YOUR_VIDEO_URL>", // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
  // Or use method: "direct" and file: fs.createReadStream("<PATH_TO_VIDEO_FILE>") to upload a local file up to 200 MB
});
console.log(`Created asset: id=${asset.id}`);

// 3. Check the status of the asset
console.log("Waiting for asset to be ready...");
let readyAsset = await client.assets.retrieve(asset.id);
while (readyAsset.status !== "ready" && readyAsset.status !== "failed") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  readyAsset = await client.assets.retrieve(asset.id);
}
if (readyAsset.status === "failed") {
  throw new Error(`Asset processing failed: id=${asset.id}`);
}
console.log("Asset is ready");

// 4. Analyze your video
const textStream = await client.analyzeStream({
  modelName: "pegasus1.6",
  video: { type: "asset_id", assetId: asset.id },
  promptV2: {
    inputText: "<YOUR_PROMPT>",
  },
});

// 5. Process the results
for await (const text of textStream) {
  if ("text" in text) {
    console.log(text.text);
  }
}

```

## Code explanation

#### Import the SDK and initialize the client

Create a client instance to interact with the TwelveLabs Video Understanding Platform.

#### Upload a video

Upload a video to create an asset.

#### Check the status of the asset

Asset processing is asynchronous. Poll the status of the asset until it is `ready` before you use it.

#### Analyze your video

Use the unique identifier of your asset to analyze it with a custom prompt. The platform streams the generated text as it becomes available.

#### Process the results

Process and display the generated text. This example prints the results to the standard output.

# Analyze images

Upload your images as assets, then analyze them with a custom prompt. The platform processes your request synchronously and streams the generated text. This quickstart analyzes one image; to include up to twenty in a single request, see the [complete guide](/v1.3/docs/guides/analyze-videos-and-images/images).

## Starter code

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```Python Python maxLines=12
import time
from twelvelabs import TwelveLabs
from twelvelabs.types import AnalyzeImageInput

# 1. Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")

# 2. Upload an image
asset = client.assets.create(
    method="url",
    url="<YOUR_IMAGE_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
    # Or use method="direct" and file=open("<PATH_TO_IMAGE_FILE>", "rb") to upload a local file
)
print(f"Created asset: id={asset.id}")

# 3. Check the status of the asset
print("Waiting for asset to be ready...")
while True:
    asset = client.assets.retrieve(asset.id)
    if asset.status == "ready":
        print("Asset is ready")
        break
    if asset.status == "failed":
        raise RuntimeError(f"Asset processing failed: id={asset.id}")
    time.sleep(5)

# 4. Analyze your image
image = AnalyzeImageInput(
    name="product_shot",
    asset_id=asset.id,
)
text_stream = client.analyze_stream(
    model_name="pegasus1.6",
    image=[image],
    prompt="<YOUR_PROMPT>",
)

# 5. Process the results
for text in text_stream:
    if text.event_type == "text_generation":
        print(text.text)
```

**`Node.js`**

```JavaScript Node.js maxLines=12
import { TwelveLabs } from "twelvelabs-js";
// Uncomment the next line if uploading a local file
// import fs from "fs";

// 1. Initialize the client
const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// 2. Upload an image
const asset = await client.assets.create({
  method: "url",
  url: "<YOUR_IMAGE_URL>", // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
  // Or use method: "direct" and file: fs.createReadStream("<PATH_TO_IMAGE_FILE>") to upload a local file
});
console.log(`Created asset: id=${asset.id}`);

// 3. Check the status of the asset
console.log("Waiting for asset to be ready...");
let readyAsset = await client.assets.retrieve(asset.id);
while (readyAsset.status !== "ready" && readyAsset.status !== "failed") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  readyAsset = await client.assets.retrieve(asset.id);
}
if (readyAsset.status === "failed") {
  throw new Error(`Asset processing failed: id=${asset.id}`);
}
console.log("Asset is ready");

// 4. Analyze your image
const image = { name: "product_shot", assetId: asset.id };
const textStream = await client.analyzeStream({
  modelName: "pegasus1.6",
  image: [image],
  prompt: "<YOUR_PROMPT>",
});

// 5. Process the results
for await (const text of textStream) {
  if ("text" in text) {
    console.log(text.text);
  }
}
```

## Code explanation

#### Import the SDK and initialize the client

Create a client instance to interact with the TwelveLabs Video Understanding Platform.

#### Upload an image

Upload an image to create an asset.

#### Check the status of the asset

Asset processing is asynchronous. Poll the status of the asset until it is `ready` before you use it.

#### Analyze your image

Use the unique identifier of your asset to analyze it with a custom prompt. The platform streams the generated text as it becomes available.

#### Process the results

Process and display the generated text. This example prints the results to the standard output.

> Quickstart: analyze videos and images to generate text. Working examples with core parameters.