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

Prerequisites

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

  1

  If you don’t have an account, sign up for a free account.

  2

  Go to the API Keys page.

  3

  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.

  4

  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:

  PythonNode.js

  pip install --upgrade twelvelabs

• 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 page for details.

  • Analysis method: Videos from 1 second to 1 hour. For longer videos, use the asynchronous method in the complete guide.

  • Model capabilities: See the complete requirements for videos

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

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)

Code explanation

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.

Starter code

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

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)

Code explanation