> 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. # Create video embeddings > Create embeddings for your videos. The SDK provides methods to create embeddings for your videos. To create video embeddings: 1. Create a video embedding task that uploads and processes a video. 2. Monitor the status of your task. 3. Retrieve the embeddings once the task is completed. # Methods ## Create a video embedding task **Description**: This method creates a new video embedding task that uploads a video to the platform. Your videos must meet the [requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements). > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```javascript Function signature create( request: TwelvelabsApi.embed.TasksCreateRequest, requestOptions?: Tasks.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.tasks.create({ modelName: "marengo3.0", // videoFile: "", videoUrl: "", videoStartOffsetSec: 0, videoEndOffsetSec: 10, videoClipLength: 5, videoEmbeddingScope: ["clip", "video"] }); console.log(`Task ID: ${task.id}`); ``` ### Parameters | Name | Type | Required | Description | | --------------------- | ----------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `modelName` | `string` | Yes | The name of the video understanding model to use. The following models are available: - `marengo3.0`: Enhanced model with sports intelligence and extended content support. | | `videoFile` | `File \| fs.ReadStream \| Blob` | No | The video file to upload. | | `videoUrl` | `string` | No | Specify this parameter to upload a video from a publicly accessible URL. | | `videoStartOffsetSec` | `number` | No | The start offset in seconds from the beginning of the video where processing should begin. Specifying 0 means starting from the beginning of the video. **Default**: 0, **Min**: 0, **Max**: Duration of the video minus `videoClipLength`. | | `videoEndOffsetSec` | `number` | No | The end offset in seconds from the beginning of the video where processing should stop. You must set both start and end offsets when using this parameter. **Min**: videoStartOffset + videoClipLength, **Max**: Duration of the video file. | | `videoClipLength` | `number` | No | The desired duration in seconds for each clip for which the platform generates an embedding. Ensure that the clip length does not exceed the interval between the start and end offsets. **Default**: 6, **Min**: 2, **Max**: 10. | | `videoEmbeddingScope` | `TwelvelabsApi.` `embed.` `TasksCreateRequestVideoEmbeddingScopeItem[]` | No | Defines the scope of video embedding generation. Valid values are: `["clip"]` and `["clip", "video"]`. Use the `video` scope for videos up to 10-30 seconds to maintain optimal performance. **Default**: `clip`. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `Promise` that resolves to a `TasksCreateResponse` object representing the new video embedding task. The `TasksCreateResponse` interface contains the following properties: | Name | Type | Description | | ---- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the video embedding task. You can use the identifier to retrieve the status of your task or retrieve the embedding. | \###API Reference [Create a video embedding task](/v1.3/api-reference/create-embeddings-v1/video-embeddings/create-video-embedding-task). ## Retrieve the status of a video embedding task **Description**: This method retrieves the status of a video embedding task. **Function signature and example**: **`Function signature`** ```javascript Function signature status( taskId: string, requestOptions?: Tasks.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.embed.tasks.status(""); console.log(`Task ID: ${response.id}`); console.log(`Model Name: ${response.modelName}`); console.log(`Status: ${response.status}`); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :--------------------- | :------- | :------------------------------------------------- | | `taskId` | `string` | Yes | The unique identifier of the video embedding task. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `Promise` that resolves to a `TasksStatusResponse` object containing the current status of the embedding task. The `TasksStatusResponse` interface contains the following properties: | Name | Type | Description | | ---------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier of the video embedding task. | | `status` | `string` | The status of the video indexing task. It can take one of the following values: `processing`, `ready` or `failed`. | | `modelName` | `string` | The name of the video understanding model the platform used to create the embedding. | | `videoEmbedding` | `TasksStatusResponseVideoEmbedding` | An object containing the metadata associated with the embedding. | The `TasksStatusResponseVideoEmbedding` interface contains the following properties: | Name | Type | Description | | ---------- | ------------------------ | --------------------------------------- | | `metadata` | `VideoEmbeddingMetadata` | Metadata associated with the embedding. | The `VideoEmbeddingMetadata` interface extends `BaseEmbeddingMetadata` and contains the following properties: | Name | Type | Description | | --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | `videoClipLength` | `number` | The duration for each clip in seconds. Note that the platform automatically truncates video segments shorter than 2 seconds. | | `videoEmbeddingScope` | `string[]` | The scope you've specified in the request. It can take one of the following values: `['clip']` or `['clip', 'video']`. | | `duration` | `number` | The total duration of the video in seconds. | | `inputUrl` | `string` | The URL of the media file used to generate the embedding. Present if a URL was provided in the request. | | `inputFilename` | `string` | The name of the media file used to generate the embedding. Present if a file was provided in the request. | ### API Reference [Retrieve the status of a video embedding task](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embedding-task-status). ## Wait for a video embedding task to complete **Description**: This method waits until a video embedding task is completed by periodically checking its status. If you provide a callback function, it calls the function after each status update with the current task object, allowing you to monitor progress. **Function signature and example**: **`Function signature`** ```javascript Function signature waitForDone( taskId: string, options?: { sleepInterval?: number; callback?: (task: TwelvelabsApi.embed.TasksStatusResponse) => void | Promise; }, requestOptions?: Tasks.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js"; const status = await client.embed.tasks.waitForDone("", { callback: (task: TwelvelabsApi.embed.TasksStatusResponse) => { console.log(` Status=${task.status}`); }, }); console.log(`Embedding done: ${status.status}`); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :------------------------------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | | `taskId` | `string` | Yes | The unique identifier of the task to wait for. | | `sleepInterval` | `number` | No | Sets the time in seconds to wait between status checks. Must be greater than 0. Default: 5.0. | | `callback` | `(task: TwelvelabsApi.embed.TasksStatusResponse) => void \| Promise` | No | Provides an optional function to call after each status check. The function receives the current task response. Use this to monitor progress. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `Promise` that resolves to a `TasksStatusResponse` object containing the status of your completed task. See the [Retrieve the status of a video embedding task](#retrieve-the-status-of-a-video-embedding-task) section above for complete property details. ## Retrieve video embeddings **Description**: This method retrieves embeddings for a specific video embedding task. Ensure the task status is `ready` before retrieving your embeddings. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieve( taskId: string, request?: TwelvelabsApi.embed.TasksRetrieveRequest, requestOptions?: Tasks.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const printSegments = (segments: TwelvelabsApi.BaseSegment[]) => { segments.forEach((segment) => { const first_few = segment.float?.slice(0, 5); console.log( ` embeddings: [${first_few?.join(", ")}...] (total: ${ segment.float?.length } values)` ); }); }; const task = await client.embed.tasks.retrieve("", { embeddingOption: ["visual", "audio", "transcription"] }); if (task.videoEmbedding?.segments) { printSegments(task.videoEmbedding.segments); } ``` ### Parameters | Name | Type | Required | Description | | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `taskId` | `string` | Yes | The unique identifier of your video embedding task. | | `embeddingOption` | `TwelvelabsApi.` `embed.` `TasksRetrieveRequestEmbeddingOptionItem \| TwelvelabsApi.` `embed.` `TasksRetrieveRequestEmbeddingOptionItem[]` | No | Specifies which types of embeddings to retrieve. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section. The platform returns all available embeddings if you don't provide this parameter. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `Promise` that resolves to a `TasksRetrieveResponse` object containing your embeddings. The `TasksRetrieveResponse` interface contains the following properties: | Name | Type | Description | | ---------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier of the video embedding task. | | `modelName` | `string` | The name of the video understanding model the platform used to create the embedding. | | `status` | `string` | The status of the video indexing task. It can take one of the following values: `processing`, `ready` or `failed`. | | `createdAt` | `Date` | The date and time, in the RFC 3339 format, that the video embedding task was created. | | `videoEmbedding` | `TasksRetrieveResponseVideoEmbedding` | An object containing the embeddings and metadata. | The `TasksRetrieveResponseVideoEmbedding` interface contains the following properties: | Name | Type | Description | | ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------- | | `metadata` | `VideoEmbeddingMetadata` | Metadata associated with the embedding. | | `segments` | `VideoSegment[]` | An array of objects containing the embeddings for each video segment and the associated information. | The `VideoEmbeddingMetadata` interface extends `BaseEmbeddingMetadata` and contains the following properties: | Name | Type | Description | | --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | `videoClipLength` | `number` | The duration for each clip in seconds. Note that the platform automatically truncates video segments shorter than 2 seconds. | | `videoEmbeddingScope` | `string[]` | The scope you've specified in the request. It can take one of the following values: `['clip']` or `['clip', 'video']`. | | `duration` | `number` | The total duration of the video in seconds. | | `inputUrl` | `string` | The URL of the media file used to generate the embedding. Present if a URL was provided in the request. | | `inputFilename` | `string` | The name of the media file used to generate the embedding. Present if a file was provided in the request. | The `VideoSegment` interface extends `AudioSegment` and contains the following properties: | Name | Type | Description | | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `startOffsetSec` | `number` | The start time, in seconds, from which the platform generated the embedding. | | `endOffsetSec` | `number` | The end time, in seconds, of the video segment for this embedding. | | `embeddingOption` | `string` | The type of the embedding. | | `embeddingScope` | `string` | The scope of the video embedding. | | `float` | `number[]` | An array of floating point numbers representing the embedding. You can use this array with cosine similarity for various downstream tasks. | ### API Reference [Retrieve video embeddings](/v1.3/api-reference/create-embeddings-v1/video-embeddings/retrieve-video-embeddings). # Error codes This section lists the most common error messages you may encounter while creating video embeddings. * `parameter_invalid` * The `video_clip_length` parameter is invalid. `video_clip_length` should be within 2-10 seconds long * The `video_end_offset_sec` parameter is invalid. `video_end_offset_sec` should be greater than `video_start_offset_sec` For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/error-codes) page.