> 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.

# Analyze videos

> Quickstart: analyze videos to generate text. Working example with core parameters.

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

* A basic working example
* Minimal implementation details
* Core parameters for common use cases

For a comprehensive guide, see the [Analyze videos](/v1.3/docs/guides/analyze-videos) 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

This guide shows how to upload your video as an asset and analyze it synchronously.

# 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:

  ```shell Python
  pip install twelvelabs
  ```

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

* Your video files must meet the following requirements:
  * **Upload limits**: Public video URLs up to 2 GB or local video files up to 200 MB. For local files up to 2 GB, see the [Upload and processing methods](/v1.3/docs/concepts/upload-methods) page.

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

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

# Starter code

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

```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.5",
    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)
```

```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.5",
  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

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

Upload a video to create an asset.

{/* <Note title="Note">
 For local files larger than 200 MB, use [multipart uploads](/v1.3/api-reference/upload-content/multipart-uploads). Multipart uploads support automatic retry, progress tracking, parallel chunk uploads, and improved reliability, performance, and observability.
 </Note>
  */}

You only need this step for URL uploads larger than 200 MB. The platform processes these files asynchronously.

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 and display the generated text. This example prints the results to the standard output.