This quickstart guide provides a simplified introduction to creating embeddings 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 Create embeddings 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.
• Embedding: Vector representation of your content.

Workflow

The platform generates embeddings for video, audio, image, text, and combined content. The input method depends on the content type:

• File-based content (video, audio, single image): Upload your file to create an asset, then pass the asset ID to generate embeddings.
• Text content: Provide your text directly.
• Text and image: Upload images as assets and pass their IDs along with your text.

Use these embeddings for similarity search, content classification, clustering, recommendations, or Retrieval-Augmented Generation (RAG).

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 twelvelabs

• Your media files must meet the following requirements:

  • Upload limits: Public video and audio URLs up to 4 GB, local video and audio files up to 200 MB, and image files up to 5 MB. For local files up to 4 GB, see the Upload and processing methods page.

  • Embedding method: Video and audio files up to 10 minutes. For video and audio files up to 4 hours, use the asynchronous method in the complete guide.

  • Model capabilities: See the complete requirements for video files, audio files, and image files

Starter code

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

1
import time
2
from twelvelabs import TwelveLabs, VideoInputRequest, MediaSource
3
4
# 1. Initialize the client
5
client = TwelveLabs(api_key="<YOUR_API_KEY>")
6
7
# 2. Upload a video
8
asset = client.assets.create(
9
    method="url",
10
    url="<YOUR_VIDEO_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
11
    # Or use method="direct" and file=open("<PATH_TO_VIDEO_FILE>", "rb") to upload a local file up to 200 MB
12
)
13
print(f"Created asset: id={asset.id}")
14
15
# 3. Check the status of the asset
16
print("Waiting for asset to be ready...")
17
while True:
18
    asset = client.assets.retrieve(asset.id)
19
    if asset.status == "ready":
20
        print("Asset is ready")
21
        break
22
    if asset.status == "failed":
23
        raise RuntimeError(f"Asset processing failed: id={asset.id}")
24
    time.sleep(5)
25
26
# 4. Create video embeddings
27
response = client.embed.v_2.create(
28
    input_type="video",
29
    model_name="marengo3.0",
30
    video=VideoInputRequest(
31
        media_source=MediaSource(
32
            asset_id=asset.id,
33
        ),
34
    ),
35
)
36
37
# 5. Process the results
38
print(f"\n{'='*80}")
39
print(f"EMBEDDINGS SUMMARY: {len(response.data)} total embeddings")
40
print(f"{'='*80}\n")
41
42
for idx, embedding_data in enumerate(response.data, 1):
43
    print(f"[{idx}/{len(response.data)}] {embedding_data.embedding_option.upper()} | {embedding_data.embedding_scope.upper()}")
44
    print(f"├─ Time range: {embedding_data.start_sec}s - {embedding_data.end_sec}s")
45
    print(f"├─ Dimensions: {len(embedding_data.embedding)}")
46
    print(f"└─ First 10 values: {embedding_data.embedding[:10]}")
47
    print()

Code explanation