> 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/create-embeddings/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Create embeddings

> Quickstart: create multimodal embeddings. Working examples with core parameters.

This quickstart guide provides a simplified introduction to creating embeddings using the TwelveLabs Video Understanding Platform. It includes the following:

* A working example for each method: embed a query and embed content at scale
* Minimal implementation details
* Core parameters for common use cases

For comprehensive guides, see the [Create embeddings](/v1.3/docs/guides/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.
* **Embedding task**: An asynchronous operation for processing your content and creating embeddings. Contains a status and the resulting embeddings when complete.

# Workflow

The platform provides two methods to create embeddings. Choose the method that fits your use case:

#### [Embed a query](#embed-a-query)

Embed the text and media you search with. Returns one embedding in the response.

#### [Embed content at scale](#embed-content-at-scale)

Embed the files you search through, one per request. Returns a task to poll.

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:

  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 media files must meet the following requirements:
  * **Embed a query**: Up to 10 media sources (images, video, or audio). Each media source can be up to 32 MB, and video and audio can be up to 30 seconds. Your text can be up to 2,000 tokens.
  * **Embed content at scale**: Public video and audio URLs up to 4 GB, local video and audio files up to 200 MB, and images up to 32 MB. For local files up to 4 GB, see the [Upload and processing methods](/v1.3/docs/concepts/upload-methods) page. For documents, local files up to 200 MB or public URLs up to 512 MB.
  * **Model capabilities**: See the complete [input requirements](/v1.3/docs/concepts/models/marengo/marengo-3-5#input-requirements) for Marengo 3.5.

# Embed a query

Create a single embedding from your text. To create a combined embedding, add up to 10 image, video, or audio files to your request. The platform processes your request synchronously and returns the embedding in the response.

## Starter code

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

**`Python`**

```Python Python maxLines=12
from twelvelabs import (
    TwelveLabs,
    MultiInputRequest,
    # To combine your text with media, uncomment the next line:
    # MultiInputMediaSource,
)

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

# 2. Create an embedding for your query
response = client.embed.v_2.create(
    input_type="multi_input",
    model_name="marengo3.5",
    multi_input=MultiInputRequest(
        input_text="<YOUR_TEXT>",
        # To combine your text with media, uncomment the following lines:
        # media_sources=[
        #     MultiInputMediaSource(
        #         media_type="image", # Or "video" or "audio"
        #         asset_id="<YOUR_ASSET_ID>", # Upload your file first to create a reusable asset
        #         # Or use url="<YOUR_MEDIA_URL>" for a direct link to a raw media file. Video hosting platforms and cloud storage sharing links are not supported
        #     ),
        # ],
    ),
)

# 3. Process the results
print(f"Number of embeddings: {len(response.data)}")
for embedding_data in response.data:
    print(f"Embedding dimensions: {len(embedding_data.embedding)}")
    print(f"First 10 values: {embedding_data.embedding[:10]}")
```

**`Node.js`**

```JavaScript Node.js maxLines=12
import { TwelveLabs } from "twelvelabs-js";

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

// 2. Create an embedding for your query
const response = await client.embed.v2.create({
    inputType: "multi_input",
    modelName: "marengo3.5",
    multiInput: {
        inputText: "<YOUR_TEXT>",
        // To combine your text with media, uncomment the following lines:
        // mediaSources: [
        //     {
        //         mediaType: "image", // Or "video" or "audio"
        //         assetId: "<YOUR_ASSET_ID>", // Upload your file first to create a reusable asset
        //         // Or use url: "<YOUR_MEDIA_URL>" for a direct link to a raw media file. Video hosting platforms and cloud storage sharing links are not supported
        //     },
        // ],
    },
});

// 3. Process the results
console.log(`Number of embeddings: ${response.data.length}`);
for (const embeddingData of response.data) {
    console.log(`Embedding dimensions: ${embeddingData.embedding.length}`);
    console.log(`First 10 values: ${embeddingData.embedding.slice(0, 10)}`);
}
```

## Code explanation

#### Import the SDK and initialize the client

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

#### Create an embedding for your query

Create an embedding for your text. To combine your text with an image, video, or audio file, uncomment the media source lines.

#### Process the results

Process and display the embeddings. This example prints the embedding dimensions and first 10 values to the standard output.

# Embed content at scale

Create embeddings for your media files: video, audio, images, and documents. The platform processes your files asynchronously, one file per request. Use this method for long files and large collections. This example embeds one video; repeat the request for each file. The request differs for each type of content.

> **Retention policy**
>
> Embeddings created with the asynchronous method are stored for seven days. After this, you must recreate them to obtain the results again.

## 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, AsyncVideoInputRequest, MediaSource

# 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. Create an embedding task
task = client.embed.v_2.tasks.create(
    input_type="video",
    model_name="marengo3.5",
    video=AsyncVideoInputRequest(
        media_source=MediaSource(
            asset_id=asset.id,
            # url="<YOUR_VIDEO_URL>", # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
            # base_64_string="<BASE_64_ENCODED_DATA>",
        ),
        embedding_option=["visual", "audio"],
    ),
)
print(f"Task ID: {task.id}")

# 5. Monitor the status
while True:
    task = client.embed.v_2.tasks.retrieve(task_id=task.id)
    if task.status == "ready":
        print("Task completed")
        break
    elif task.status == "failed":
        print("Task failed")
        break
    else:
        print("Task still processing...")
        time.sleep(5)

# 6. Process the results
print(f"Number of embeddings: {len(task.data)}")
for embedding_data in task.data:
    print(f"[{embedding_data.embedding_option}] {embedding_data.start_sec}s - {embedding_data.end_sec}s")
    print(f"Embedding dimensions: {len(embedding_data.embedding)}")
    print(f"First 10 values: {embedding_data.embedding[:10]}")
```

**`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. Create an embedding task
let task = await client.embed.v2.tasks.create({
    inputType: "video",
    modelName: "marengo3.5",
    video: {
        mediaSource: {
            assetId: asset.id,
            // url: "<YOUR_VIDEO_URL>", // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
            // base64String: "<BASE_64_ENCODED_DATA>",
        },
        embeddingOption: ["visual", "audio"],
    },
});
console.log(`Task ID: ${task.id}`);

// 5. Monitor the status
while (true) {
    task = await client.embed.v2.tasks.retrieve(task.id);
    if (task.status === "ready") {
        console.log("Task completed");
        break;
    } else if (task.status === "failed") {
        console.log("Task failed");
        break;
    } else {
        console.log("Task still processing...");
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

// 6. Process the results
console.log(`Number of embeddings: ${task.data.length}`);
for (const embeddingData of task.data) {
    console.log(`[${embeddingData.embeddingOption}] ${embeddingData.startSec}s - ${embeddingData.endSec}s`);
    console.log(`Embedding dimensions: ${embeddingData.embedding.length}`);
    console.log(`First 10 values: ${embeddingData.embedding.slice(0, 10)}`);
}
```

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

#### Create an embedding task

Create an embedding task using the identifier of the asset.

#### Monitor the status

Poll the task until it reaches the `ready` state.

#### Process the results

Process and display the embeddings. This example prints the time range, embedding dimensions, and first 10 values for each segment to the standard output.

> Quickstart: create multimodal embeddings. Working examples with core parameters.