> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/v1.3/sdk-reference/node-js/create-embeddings-v-2/create-async-embeddings/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Create async embeddings > Create embeddings asynchronously for audio, video, images, and documents. The `Embed.V2.Tasks` interface provides methods to create embeddings asynchronously for audio, video, images, and documents. Creating embeddings asynchronously requires three steps: 1. Create a task using the `create` method. The platform returns a task ID. 2. Poll for the status of the task using the `retrieve` method. Wait until the status is `ready`. 3. Retrieve the embeddings from the response when the status is `ready` using the `retrieve` method. # Methods ## List embedding tasks **Description**: This method returns a list of the async embedding tasks in your account. The platform returns your async embedding tasks sorted by creation date, with the newest at the top of the list. > **Notes** > > * Embeddings are stored for seven days. > * When you invoke this method without specifying the `started_at` and `ended_at` parameters, the platform returns all the async embedding tasks created within the last seven days. **Function signature and example**: **`Function signature`** ```javascript Function signature list( request?: TwelvelabsApi.embed.v2.TasksListRequest, requestOptions?: Tasks.RequestOptions ): Promise> ``` **`List embedding tasks`** ```javascript List embedding tasks import { TwelveLabs } from "twelvelabs-js"; const response = await client.embed.v2.tasks.list({ page: 1, pageLimit: 10, }); console.log("Embedding tasks:"); for await (const task of response) { console.log(` Task ID: ${task.id}`); console.log(` Model: ${task.modelName}`); console.log(` Status: ${task.status}`); console.log(` Created: ${task.createdAt}`); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :---------------------------------------- | :------- | :-------------------------------------- | | `request` | `TwelvelabsApi.embed.v2.TasksListRequest` | No | Parameters for listing embedding tasks. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.embed.v2.TasksListRequest` interface contains the following properties: | Name | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `startedAt` | `string` | No | Retrieve the embedding tasks that were created after the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). | | `endedAt` | `string` | No | Retrieve the embedding tasks that were created before the given date and time, expressed in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). | | `status` | `string` | No | Filter the embedding tasks by their current status. Values: `processing`, `ready`, or `failed`. | | `page` | `number` | No | A number that identifies the page to retrieve. Default: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. Default: `10`. Max: `50`. | ### Return value Returns a `Promise` that resolves to a `Page` object that allows you to iterate through the paginated task results. The `Page` class contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `getNextPage()` | `Promise>` | Retrieves the next page and returns the updated `Page` object. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `TwelvelabsApi.MediaEmbeddingTask` interface contains the following properties: | Name | Type | Description | | ------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the embedding task. | | `modelName` | `string` | The name of the video understanding model the platform used to create the embedding. | | `status` | `string` | A string indicating the status of the embedding task. It can take one of the following values: `processing`, `ready` or `failed`. | | `createdAt` | `Date` | The date and time when the task was created. | | `updatedAt` | `Date` | The date and time when the task was last updated. | | `videoEmbedding` | `TwelvelabsApi.MediaEmbeddingTaskVideoEmbedding` | An object containing the metadata associated with the embedding. See [VideoEmbeddingMetadata](#videoembeddingmetadata) for details. | | `audioEmbedding` | `TwelvelabsApi.MediaEmbeddingTaskAudioEmbedding` | An object containing the metadata associated with the embedding. See [AudioEmbeddingMetadata](#audioembeddingmetadata) for details. | | `documentEmbedding` | `TwelvelabsApi.MediaEmbeddingTaskDocumentEmbedding` | An object containing the metadata associated with the embedding. Present only for `document` tasks created with Marengo 3.5. See [DocumentEmbeddingMetadata](#documentembeddingmetadata) for details. | | `imageEmbedding` | `TwelvelabsApi.MediaEmbeddingTaskImageEmbedding` | An object containing the metadata associated with the embedding. Present only for `image` tasks created with Marengo 3.5. See [ImageEmbeddingMetadata](#imageembeddingmetadata) for details. | Each of the four objects above wraps a single `metadata` field. All four metadata interfaces extend `TwelvelabsApi.BaseEmbeddingMetadata`, which contributes the following properties: | Name | Type | Description | | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------- | | `inputUrl` | `Optional` | The URL of the media file used to generate the embedding. Present if a URL was provided in the request. | | `inputFilename` | `Optional` | The name of the media file used to generate the embedding. Present if a file was provided in the request. | #### VideoEmbeddingMetadata The `TwelvelabsApi.VideoEmbeddingMetadata` interface contains the metadata associated with the embedding. | Name | Type | Description | | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `videoClipLength` | `Optional` | The duration for each clip in seconds, as specified in the request. Note that the platform automatically truncates video segments shorter than 2 seconds. For a 31-second video divided into 6-second segments, the final 1-second segment will be truncated. This truncation only applies to the last segment if it does not meet the minimum length requirement of 2 seconds. | | `videoEmbeddingScope` | `Optional` | The scope you've specified in the request. | | `videoEmbeddingOption` | `Optional` | The `embeddingOption` values used to generate the embedding. | | `duration` | `Optional` | The total duration of the video in seconds. | #### AudioEmbeddingMetadata The `TwelvelabsApi.AudioEmbeddingMetadata` interface contains the metadata associated with the embedding. | Name | Type | Description | | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- | | `audioEmbeddingOption` | `Optional` | The type of the embedding. It can take one of the following values: `["audio"]` or `["transcription"]`. | | `audioEmbeddingScope` | `Optional` | The scope you've specified in the request. | | `duration` | `Optional` | The total duration of the audio in seconds. | | `startOffsetSec` | `Optional` | The start offset in seconds from the beginning of the audio where processing should begin. | | `endOffsetSec` | `Optional` | The end offset in seconds from the beginning of the audio where processing should end. | #### DocumentEmbeddingMetadata The `TwelvelabsApi.DocumentEmbeddingMetadata` interface contains the metadata associated with the embedding. Only Marengo 3.5 returns this object. | Name | Type | Description | | ------------------------- | -------------------- | ------------------------------------------------------------ | | `documentEmbeddingOption` | `Optional` | The `embeddingOption` values used to generate the embedding. | | `documentEmbeddingScope` | `Optional` | The `embeddingScope` values used to generate the embedding. | #### ImageEmbeddingMetadata The `TwelvelabsApi.ImageEmbeddingMetadata` interface contains the metadata associated with the embedding. Only Marengo 3.5 returns this object. | Name | Type | Description | | ---------------------- | -------------------- | --------------------------------------------------------------------------------- | | `imageEmbeddingOption` | `Optional` | The `embeddingOption` values used to generate the embedding. Always `["visual"]`. | | `imageEmbeddingScope` | `Optional` | The `embeddingScope` values used to generate the embedding. Always `["asset"]`. | ### API Reference [List async embedding tasks](/v1.3/api-reference/create-embeddings-v2/list-async-embedding-tasks) ## Create an async embedding task **Description**: This method creates embeddings for audio, video, images, and documents asynchronously. Use this method to embed content at scale, such as long files or the media files you want to make searchable. For a query, or for results you need in the same request, use the [Create embeddings](/v1.3/sdk-reference/node-js/embed-v2/sync) interface instead. The content this method accepts depends on the model. Both models embed audio and video. Marengo 3.5 also embeds images and PDF files. For the formats, resolutions, file sizes, and duration limits each model accepts, see the input requirements for [Marengo 3.5](/v1.3/docs/concepts/models/marengo/marengo-3-5#input-requirements) or [Marengo 3.0](/v1.3/docs/concepts/models/marengo/marengo-3-0#input-requirements). > **Notes** > > * Creating a task validates only basic metadata and playability, not the full file. A file can pass this check but still fail later during embedding. When you retrieve the results, check the `status` field. If it is `failed`, the `error.message` field contains the reason. > * This method is rate-limited. With Marengo 3.5, the platform counts input tokens for each type of content. A task can exceed a limit before you see an error. For details, see [Input token limits for embedding](/v1.3/docs/get-started/rate-limits#input-token-limits-for-embedding). > * Embeddings are stored for seven days. **Function signature and example**: **`Function signature`** ```javascript Function signature create( request: TwelvelabsApi.embed.v2.CreateAsyncEmbeddingRequest, requestOptions?: Tasks.RequestOptions ): core.HttpResponsePromise ``` **`Video with fixed segmentation`** ```javascript Video with fixed segmentation import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.v2.tasks.create({ inputType: "video", modelName: "marengo3.5", video: { mediaSource: { url: "", }, startSec: 0.0, endSec: 50.0, segmentation: { temporal: { strategy: "fixed", fixed: { durationSec: 10, }, }, }, embeddingOption: ["visual", "audio"], embeddingScope: ["clip", "asset"], embeddingType: ["separate_embedding", "fused_embedding"], }, }); console.log(`Task ID: ${task.id}`); console.log(`Status: ${task.status}`); ``` **`Video fused with time-based metadata`** ```javascript Video fused with time-based metadata import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.v2.tasks.create({ inputType: "video", modelName: "marengo3.5", video: { mediaSource: { assetId: "", }, embeddingOption: ["visual", "audio"], embeddingType: ["separate_embedding", "fused_embedding"], embeddingScope: ["clip"], timeBasedMetadata: [ { start: 42.3, end: 42.3, text: "Shot made. LeBron James dunk. Assist: D'Angelo Russell. +2 LAL. 88-84.", }, ], }, embeddingUncertainty: true, }); console.log(`Task ID: ${task.id}`); console.log(`Status: ${task.status}`); ``` **`PDF document, page-level and whole-asset embeddings`** ```javascript PDF document, page-level and whole-asset embeddings import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.v2.tasks.create({ inputType: "document", modelName: "marengo3.5", document: { mediaSource: { assetId: "", }, embeddingOption: ["visual"], embeddingType: ["separate_embedding"], embeddingScope: ["local", "asset"], }, embeddingUncertainty: true, }); console.log(`Task ID: ${task.id}`); console.log(`Status: ${task.status}`); ``` **`Image with single asset-scope visual embedding`** ```javascript Image with single asset-scope visual embedding import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.v2.tasks.create({ inputType: "image", modelName: "marengo3.5", image: { mediaSource: { assetId: "", }, }, embeddingUncertainty: true, }); console.log(`Task ID: ${task.id}`); console.log(`Status: ${task.status}`); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :--------------------------------------------------- | :------- | :----------------------------------------------- | | `request` | `TwelvelabsApi.embed.v2.CreateAsyncEmbeddingRequest` | Yes | Parameters for creating an async embedding task. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.embed.v2.CreateAsyncEmbeddingRequest` interface contains the following properties: | Name | Type | Required | Description | | ---------------------- | ------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inputType` | `TwelvelabsApi.embed.v2.CreateAsyncEmbeddingRequestInputType` | Yes | The type of content for the embeddings. Values: - `audio`: An audio file. - `video`: A video file. - `document`: A PDF file. Requires Marengo 3.5. - `image`: An image file. Requires Marengo 3.5. | | `modelName` | `TwelvelabsApi.embed.v2.CreateAsyncEmbeddingRequestModelName` | Yes | The embedding model to use. Values: - `marengo3.5`: For details about this version, see the [Marengo 3.5](/v1.3/docs/concepts/models/marengo/marengo-3-5) page. - `marengo3.0`: For details about this version, see the [Marengo 3.0](/v1.3/docs/concepts/models/marengo/marengo-3-0) page. | | `audio` | `TwelvelabsApi.AsyncAudioInputRequest` | No | Audio input configuration. Required when `inputType` is `audio`. See [AsyncAudioInputRequest](#asyncaudioinputrequest) for details. | | `video` | `TwelvelabsApi.AsyncVideoInputRequest` | No | Video input configuration. Required when `inputType` is `video`. See [AsyncVideoInputRequest](#asyncvideoinputrequest) for details. | | `document` | `TwelvelabsApi.AsyncDocumentInputRequest` | No | Document input configuration. Required when `inputType` is `document`. See [AsyncDocumentInputRequest](#asyncdocumentinputrequest) for details. Requires Marengo 3.5. | | `image` | `TwelvelabsApi.AsyncImageInputRequest` | No | Image input configuration. Required when `inputType` is `image`. See [AsyncImageInputRequest](#asyncimageinputrequest) for details. Requires Marengo 3.5. | | `embeddingUncertainty` | `boolean` | No | Set this parameter to `true` to receive a `data[].embeddingUncertainty` field in the response, representing a per-dimension uncertainty vector with the same length as the `embedding` array. A higher value shows lower confidence in that dimension. Requires Marengo 3.5. To use this parameter with audio or video input, exclude the `asset` scope from the `embeddingScope` field. For example, set `video.embeddingScope` to `["clip"]`. The field defaults to `["clip", "asset"]`, so a request that keeps the default returns a `400` error. This restriction does not apply to `document` and `image` input. | #### AsyncAudioInputRequest The `TwelvelabsApi.AsyncAudioInputRequest` interface specifies the configuration for processing audio content. Required when `inputType` is `audio`. | Name | Type | Required | Description | | ------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaSource` | `TwelvelabsApi.MediaSource` | Yes | Specifies the source of the audio file. See [MediaSource](#mediasource) for details. | | `startSec` | `number` | No | The start time in seconds for processing the audio file. Use this parameter to process a portion of the audio file starting from a specific time. **Default**: 0 (start from the beginning). | | `endSec` | `number` | No | The end time in seconds for processing the audio file. Use this parameter to process a portion of the audio file ending at a specific time. The end time must be greater than the start time. **Default**: End of the audio file | | `segmentation` | `TwelvelabsApi.AsyncAudioInputRequestSegmentation` | No | Specifies how the platform divides the audio into segments. The structure of this object depends on the model version: - **With Marengo 3.5**: Place your settings in the `temporal` object. Both strategies are available: `dynamic` divides the audio into variable-length segments that follow scene changes, and `fixed` divides it into equal-length segments. Default: `temporal.dynamic`, `minDurationSec: 2`. - **With Marengo 3.0**: Provide the settings directly in this object. Only `fixed` segmentation is available. Default: `fixed`, `durationSec: 6`. Using a structure that does not match your model version returns a `400` error. See [AudioSegmentation](#audiosegmentation) and [AsyncTemporalSegmentation](#asynctemporalsegmentation) for details. | | `embeddingOption` | `TwelvelabsApi.AsyncAudioInputRequestEmbeddingOptionItem[]` | No | The types of embeddings you wish to generate. **Values**: - `audio`: Generates embeddings based on audio content (sounds, music, effects). With Marengo 3.5, this value includes speech, music, and non-dialog audio. - `transcription`: Generates embeddings based on transcribed speech. Requires Marengo 3.0. You can specify multiple values to generate different types of embeddings for the same audio. **Default**: `["audio", "transcription"]` for Marengo 3.0; `["audio"]` for Marengo 3.5. | | `embeddingScope` | `TwelvelabsApi.AsyncAudioInputRequestEmbeddingScopeItem[]` | No | The scope for which you wish to generate embeddings. **Values**: - `clip`: Generates one embedding for each segment. Works with both Marengo 3.0 and Marengo 3.5. - `local`: Generates one embedding for each segment. Equivalent to `clip` when using Marengo 3.5. - `asset`: Generates one embedding for the entire audio file You can specify multiple scopes to generate embeddings at different levels. **Default**: `["clip", "asset"]` | | `embeddingType` | `TwelvelabsApi.AsyncAudioInputRequestEmbeddingTypeItem[]` | No | Specifies how to structure the embedding. Include this parameter only when the `embeddingOption` parameter contains at least two values. **Values**: - `separate_embedding`: Returns separate embeddings for each modality specified in the `embeddingOption` parameter. - `fused_embedding`: Returns a single combined embedding that integrates all modalities into one vector. With Marengo 3.5, this value requires the `timeBasedMetadata` field. Specify both values to receive separate and fused embeddings in the same response. **Default**: `separate_embedding`. | | `timeBasedMetadata` | `TwelvelabsApi.TimeBasedMetadataEntry[]` | No | Your own time-aligned text, such as a stats feed or scene descriptions. The platform folds each entry into the fused embedding of the segments it overlaps in time, and it affects only that embedding. Requires the `fused_embedding` value in the `embeddingType` field. This field is supported only with Marengo 3.5. See [TimeBasedMetadataEntry](#timebasedmetadataentry) for details. | #### AsyncVideoInputRequest The `TwelvelabsApi.AsyncVideoInputRequest` interface specifies the configuration for processing video content. Required when `inputType` is `video`. | Name | Type | Required | Description | | ------------------- | ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaSource` | `TwelvelabsApi.MediaSource` | Yes | Specifies the source of the video file. See [MediaSource](#mediasource) for details. | | `startSec` | `number` | No | The start time in seconds for processing the video file. Use this parameter to process a portion of the video file starting from a specific time. **Default**: 0 (start from the beginning) | | `endSec` | `number` | No | The end time in seconds for processing the video file. Use this parameter to process a portion of the video file ending at a specific time. The end time must be greater than the start time. **Default**: End of the video file | | `segmentation` | `TwelvelabsApi.AsyncVideoInputRequestSegmentation` | No | Specifies how the platform divides the video into segments. The structure of this object depends on the model version: - **With Marengo 3.5**: Place your settings in the `temporal` object. Both strategies are available: `dynamic` divides the video into variable-length segments that follow scene changes, and `fixed` divides it into equal-length segments. Default: `temporal.dynamic`, `minDurationSec: 2`. - **With Marengo 3.0**: Provide the settings directly in this object. Default: `dynamic`, `minDurationSec: 4`. Using a structure that does not match your model version returns a `400` error. See [VideoSegmentation](#videosegmentation) and [AsyncTemporalSegmentation](#asynctemporalsegmentation) for details. | | `embeddingOption` | `TwelvelabsApi.AsyncVideoInputRequestEmbeddingOptionItem[]` | No | The types of embeddings to generate for the video. **Values**: - `visual`: Generates embeddings based on visual content (scenes, objects, actions) - `audio`: Generates embeddings based on audio content (sounds, music, effects). With Marengo 3.5, this value includes speech, music, and non-dialog audio. - `transcription`: Generates embeddings based on transcribed speech. Requires Marengo 3.0. You can specify multiple values to generate different types of embeddings for the same video. **Default**: `["visual", "audio", "transcription"]` for Marengo 3.0; `["visual", "audio"]` for Marengo 3.5. | | `embeddingScope` | `TwelvelabsApi.AsyncVideoInputRequestEmbeddingScopeItem[]` | No | The scope for which you wish to generate embeddings. **Values**: - `clip`: Generates one embedding for each segment. Works with both Marengo 3.0 and Marengo 3.5. - `local`: Generates one embedding for each segment. Equivalent to `clip` when using Marengo 3.5. - `asset`: Generates one embedding for the entire video file. Use this scope for videos up to 10-30 seconds to maintain optimal performance. You can specify multiple scopes to generate embeddings at different levels. **Default**: `["clip", "asset"]` | | `embeddingType` | `TwelvelabsApi.AsyncVideoInputRequestEmbeddingTypeItem[]` | No | Specifies how to structure the embedding. Include this parameter only when `embeddingOption` contains at least two values. **Values**: - `separate_embedding`: Returns separate embeddings per modality specified in the `embeddingOption` field - `fused_embedding`: Returns a single embedding that combines all modalities into one vector. With Marengo 3.5, this value requires the `timeBasedMetadata` field. Specify both values to receive separate and fused embeddings in the same response. **Default**: `separate_embedding`. | | `timeBasedMetadata` | `TwelvelabsApi.TimeBasedMetadataEntry[]` | No | Your own time-aligned text, such as a stats feed or scene descriptions, which you can generate by [segmenting a video with Pegasus](/v1.3/docs/guides/segment-videos). The platform folds each entry into the fused embedding of the segments it overlaps in time, and it affects only that embedding. Requires the `fused_embedding` value in the `embeddingType` field. This field is supported only with Marengo 3.5. See [TimeBasedMetadataEntry](#timebasedmetadataentry) for details. | #### TimeBasedMetadataEntry One time-aligned metadata entry. The platform folds the text of the entry into the fused embedding of every segment that overlaps the time range of the entry. Used by the `AsyncAudioInputRequest.timeBasedMetadata` and `AsyncVideoInputRequest.timeBasedMetadata` fields. Not applicable to the `AsyncDocumentInputRequest` interface. Requires Marengo 3.5. | Name | Type | Required | Description | | ------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start` | `number` | Yes | The start time of the entry in seconds, measured from the beginning of the asset. Set the same value in the `end` field for an event that happens at a single point in time, such as one entry in a stats feed. | | `end` | `number` | Yes | The end time of the entry in seconds, measured from the beginning of the asset. | | `text` | `string` | Yes | The text to fold into the fused embedding of the overlapping segments. | #### AsyncDocumentInputRequest The `TwelvelabsApi.AsyncDocumentInputRequest` interface specifies the configuration for processing documents. Requires Marengo 3.5. The platform embeds the rendered pages of your PDF file with `embeddingOption: ["visual"]`, one embedding per page. | Name | Type | Required | Description | | ----------------- | -------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaSource` | `TwelvelabsApi.MediaSource` | Yes | Specifies the source of the document file. See [MediaSource](#mediasource) for details. | | `embeddingOption` | `TwelvelabsApi.AsyncDocumentInputRequestEmbeddingOptionItem[]` | No | The type of content to embed. **Values**: - `visual`: Embeds the rendered pages. Valid for PDF files. - `text`: Not supported. Returns a `400` error. | | `embeddingType` | `TwelvelabsApi.AsyncDocumentInputRequestEmbeddingTypeItem[]` | No | Specifies how to structure the embedding. **Values**: - `separate_embedding`: Returns one embedding per requested `embeddingScope`. - `fused_embedding`: Returns a `400` error. Documents have a single modality. **Default**: `separate_embedding`. | | `embeddingScope` | `TwelvelabsApi.AsyncDocumentInputRequestEmbeddingScopeItem[]` | No | The scope for which you wish to generate embeddings. **Values**: - `local`: Returns one embedding per page. The only supported scope for PDF files, and the default. - `asset`: Not supported for PDF files. | #### AsyncImageInputRequest The `TwelvelabsApi.AsyncImageInputRequest` interface specifies the configuration for processing image content. Required when `inputType` is `image`. Requires Marengo 3.5. The image can be up to 32 MB before encoding, whichever of the three fields you use. For an image, the `embeddingOption`, `embeddingType`, and `embeddingScope` fields each accept a single value; any other value returns a `400` error. | Name | Type | Required | Description | | ----------------- | ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `mediaSource` | `TwelvelabsApi.MediaSource` | Yes | Specifies the source of the image file. See [MediaSource](#mediasource) for details. | | `embeddingOption` | `TwelvelabsApi.AsyncImageInputRequestEmbeddingOptionItem[]` | No | The type of embedding to generate for the image. Always `visual`. | | `embeddingType` | `TwelvelabsApi.AsyncImageInputRequestEmbeddingTypeItem[]` | No | Specifies how to structure the embedding. Always `separate_embedding`. | | `embeddingScope` | `TwelvelabsApi.AsyncImageInputRequestEmbeddingScopeItem[]` | No | The scope for which to generate embeddings. Always `asset`, which produces one embedding for the entire image. | #### MediaSource The `TwelvelabsApi.MediaSource` interface specifies the source of the media file. Provide exactly one of the following: | Name | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `base64String` | `string` | No | The base64-encoded media data. The decoded file can be up to 36 MB; encoded, it can be up to 48 MB. | | `url` | `string` | No | The publicly accessible URL of the media file. Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported. | | `assetId` | `string` | No | The unique identifier of an asset from a [direct](/v1.3/sdk-reference/node-js/upload-content) or [multipart](/v1.3/sdk-reference/node-js/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use [`assets.retrieve`](/v1.3/sdk-reference/node-js/manage-assets#retrieve-an-asset) to check the status. | #### AudioSegmentation The `TwelvelabsApi.AudioSegmentation` interface specifies how the platform divides the audio into segments using fixed-length intervals. | Name | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `strategy` | `TwelvelabsApi.AudioSegmentationStrategy` | Yes | The segmentation strategy. Value: `fixed`. | | `fixed` | `TwelvelabsApi.AudioSegmentationFixed` | Yes | Configuration for fixed segmentation. This object is required when the `strategy` field is `fixed`. See [AudioSegmentationFixed](#audiosegmentationfixed) for details. | #### AudioSegmentationFixed The `TwelvelabsApi.AudioSegmentationFixed` interface configures fixed-length segmentation for audio. | Name | Type | Required | Description | | ------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `durationSec` | `number` | Yes | The duration in seconds for each segment. The platform divides the audio into segments of this exact length. The final segment may be shorter if the audio duration is not evenly divisible. **Min**: `2`. **Max**: `10`. **Example**: With `duration_sec: 5`, a 12-second audio file produces segments: \[0-5s], \[5-10s], \[10-12s]. | #### VideoSegmentation The `TwelvelabsApi.VideoSegmentation` type specifies how the platform divides the video into segments. Use one of the following: **Fixed segmentation**: Divides the video into equal-length segments: | Name | Type | Required | Description | | ---------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `strategy` | `"fixed"` | Yes | The segmentation strategy. Value: `fixed`. | | `fixed` | `TwelvelabsApi.VideoSegmentationFixedFixed` | Yes | Configuration for fixed segmentation. See [VideoSegmentationFixedFixed](#videosegmentationfixedfixed) for details. | **Dynamic segmentation**: Divides the video into adaptive segments based on scene changes: | Name | Type | Required | Description | | ---------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `strategy` | `"dynamic"` | Yes | The segmentation strategy. Value: `dynamic`. | | `dynamic` | `TwelvelabsApi.VideoSegmentationDynamicDynamic` | Yes | Configuration for dynamic segmentation. See [VideoSegmentationDynamicDynamic](#videosegmentationdynamicdynamic) for details. | #### VideoSegmentationFixedFixed The `TwelvelabsApi.VideoSegmentationFixedFixed` interface configures fixed-length segmentation for video. | Name | Type | Required | Description | | ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `durationSec` | `number` | Yes | The duration in seconds for each segment. The platform divides the video into segments of this exact length. The final segment may be shorter if the video duration is not evenly divisible. **Min**: `2`. **Max**: `10`. **Example**: With `duration_sec: 5`, a 12-second video produces segments: \[0-5s], \[5-10s], \[10-12s]. | #### VideoSegmentationDynamicDynamic The `TwelvelabsApi.VideoSegmentationDynamicDynamic` interface configures dynamic segmentation for video based on scene changes. | Name | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `minDurationSec` | `number` | Yes | The minimum duration in seconds for each segment. The platform divides the video into segments that are at least this long. Segments adapt to scene changes and content boundaries and may be longer than the minimum. **Min**: `2`. **Max**: `5`. **Example**: With `min_duration_sec: 3`, segments might be: \[0-3.2s], \[3.2-7.8s], \[7.8-12.1s] | #### AsyncTemporalSegmentation The `TwelvelabsApi.AsyncTemporalSegmentation` interface wraps your settings in a `temporal` object. Use with Marengo 3.5. | Name | Type | Required | Description | | ---------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `temporal` | `TwelvelabsApi.TemporalSegmentation` | Yes | Specifies how the platform divides the file into segments. See [TemporalSegmentation](#temporalsegmentation) for details. | #### TemporalSegmentation The `TwelvelabsApi.TemporalSegmentation` type specifies how the platform divides the file into segments. The `strategy` field selects one variant: **Dynamic segmentation**: Creates variable-length segments that align with scene or content boundaries. Use this for content-aware segmentation. | Name | Type | Required | Description | | ---------- | -------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `strategy` | `"dynamic"` | Yes | Must be `dynamic`. Identifies this as the content-aware segmentation variant. | | `dynamic` | `TwelvelabsApi.TemporalSegmentationDynamicDynamic` | Yes | Configuration for dynamic segmentation. This object is required when `strategy` is `dynamic`. See [TemporalSegmentationDynamicDynamic](#temporalsegmentationdynamicdynamic) for details. | **Fixed segmentation**: Creates equal-length segments. Use this for consistent timing. | Name | Type | Required | Description | | ---------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `strategy` | `"fixed"` | Yes | Must be `fixed`. Identifies this as the equal-length segmentation variant. | | `fixed` | `TwelvelabsApi.TemporalSegmentationFixedFixed` | Yes | Configuration for fixed segmentation. This object is required when `strategy` is `fixed`. See [TemporalSegmentationFixedFixed](#temporalsegmentationfixedfixed) for details. | #### TemporalSegmentationDynamicDynamic The `TwelvelabsApi.TemporalSegmentationDynamicDynamic` interface configures dynamic segmentation. This object is required when `strategy` is `dynamic`. | Name | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `minDurationSec` | `number` | Yes | The minimum duration in seconds for each segment. The platform divides the file into segments that are at least this long. Segments adapt to scene changes and content boundaries and may be longer than the minimum. **Min**: `2`. **Max**: `5`. | #### TemporalSegmentationFixedFixed The `TwelvelabsApi.TemporalSegmentationFixedFixed` interface configures fixed segmentation. This object is required when `strategy` is `fixed`. | Name | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `durationSec` | `number` | Yes | The duration in seconds for each segment. The platform divides the file into segments of this exact length. The final segment may be shorter if the duration is not evenly divisible. **Min**: `2`. **Max**: `10`. | ### Return value Returns an `HttpResponsePromise` that resolves to a `TwelvelabsApi.embed.v2.TasksCreateResponse` object containing the task details. The `TwelvelabsApi.embed.v2.TasksCreateResponse` interface contains the following properties: | Name | Type | Description | | -------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the embedding task. | | `status` | `TwelvelabsApi.embed.v2.TasksCreateResponseStatus` | The initial status of the embedding task. Value: `processing`. | | `data` | `TwelvelabsApi.EmbeddingData[]` | Array of embedding results. Present when `status` is `ready`; `null` when `status` is `processing` or `failed`. | ### API Reference [Create an async embedding task](/v1.3/api-reference/create-embeddings-v2/create-async-embedding-task) ### Related guide * [Audio embeddings](/v1.3/docs/guides/create-embeddings/at-scale/audio) * [Video embeddings](/v1.3/docs/guides/create-embeddings/at-scale/video) ## Retrieve task status and results **Description**: This method retrieves the status and the results of an async embedding task. Invoke this method repeatedly until the `status` field is `ready` or `failed`. When the status is `ready`, use the embeddings from the response. When the status is `failed`, the `error.message` field contains the reason. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieve( taskId: string, requestOptions?: Tasks.RequestOptions ): core.HttpResponsePromise ``` **`Poll for task completion`** ```javascript Poll for task completion import { TwelveLabs } from "twelvelabs-js"; // Poll until the task is ready while (true) { const task = await client.embed.v2.tasks.retrieve(""); console.log(`Task Status: ${task.status}`); if (task.status === "ready") { break; } else if (task.status === "failed") { console.log("Task failed"); break; } else { console.log("Task still processing, waiting..."); await new Promise(resolve => setTimeout(resolve, 5000)); } } ``` **`Retrieve embeddings`** ```javascript Retrieve embeddings import { TwelveLabs } from "twelvelabs-js"; const task = await client.embed.v2.tasks.retrieve(""); console.log(`Task ID: ${task.id}`); console.log(`Status: ${task.status}`); if (task.status === "ready" && task.data) { console.log(`\nNumber of embeddings: ${task.data.length}`); for (const embeddingData of task.data) { console.log(`Type: ${embeddingData.embeddingOption}, Scope: ${embeddingData.embeddingScope}`); if (embeddingData.startSec != null) { console.log(`Time range: ${embeddingData.startSec}s - ${embeddingData.endSec}s`); } console.log(`Embedding dimensions: ${embeddingData.embedding.length}`); console.log(`First 10 values: ${embeddingData.embedding.slice(0, 10)}`); } } ``` ### Parameters | Name | Type | Required | Description | | ---------------- | ---------------------- | -------- | -------------------------------------------- | | `taskId` | `string` | Yes | The unique identifier of the embedding task. | | `requestOptions` | `Tasks.RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `HttpResponsePromise` that resolves to a `TwelvelabsApi.EmbeddingTaskResponse` object containing the task status and results. The `TwelvelabsApi.EmbeddingTaskResponse` interface contains the following properties: | Name | Type | Description | | ----------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the embedding task. | | `status` | `TwelvelabsApi.EmbeddingTaskResponseStatus` | The current status of the task. **Values**: - `processing`: The platform is creating the embeddings - `ready`: Processing is complete. Embeddings are available in the `data` field - `failed`: The task failed. The `data` field is `null`, and the `error.message` field contains the reason | | `createdAt` | `Date` | The date and time when the task was created. | | `updatedAt` | `Date` | The date and time when the task was last updated. | | `data` | `TwelvelabsApi.EmbeddingData[]` | An object containing the embedding results, or `null` otherwise. | | `usage` | `TwelvelabsApi.EmbeddingUsage` | Token counts for the request. Only Marengo 3.5 returns this field. See [EmbeddingUsage](#embeddingusage) for details. | | `metadata` | `TwelvelabsApi.EmbeddingTaskMediaMetadata` | Metadata for the media input. See [EmbeddingTaskMediaMetadata](#embeddingtaskmediametadata) for details. | | `error` | `TwelvelabsApi.EmbeddingTaskResponseError` | An object describing why the embedding task failed. Present only when `status` is `failed`. Omitted otherwise. | The `TwelvelabsApi.EmbeddingData` interface contains the following properties: | Name | Type | Description | | ---------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `embedding` | `number[]` | The embedding vector for the content. | | `embeddingUncertainty` | `Optional` | A per-dimension uncertainty vector with the same length as the `embedding` array. A higher value shows lower confidence in that dimension. Present when the request sets `embeddingUncertainty: true`. Only Marengo 3.5 returns this field. | | `embeddingOption` | `Optional` | The modality used to generate this embedding. **Values**: - `visual`: Embedding based on visual content (a video, a page of a PDF file, or an image embedded asynchronously). - `audio`: Embedding based on audio content. - `transcription`: Embedding based on transcribed speech. Returned only for content embedded with Marengo 3.0. - `text`: The platform does not return this value. - `fused`: Embedding based on a combination of the modalities specified in the request. The platform returns this embedding only for video and audio input, and only when the `embeddingType` parameter includes the `fused_embedding` value. - `null`: For text embeddings and images embedded synchronously. | | `embeddingScope` | `Optional` | The scope for which the embedding was generated. **Values**: - `clip`: Embedding for a segment. For video and audio input, one embedding per detected segment. - `page`: Embedding for one page of a document. The platform returns this value only for PDF files embedded asynchronously. - `asset`: Embedding for the entire file. For video and audio input, use this scope for content up to 10-30 seconds to maintain optimal performance. - `null`: For text embeddings and images embedded synchronously. When you request the `local` scope, the platform returns `clip` for audio and video, and `page` for PDF files. For audio, video, and document input, the `metadata.embeddingScopes` field contains the scopes you requested. | | `startSec` | `Optional` | The start time in seconds for this segment. This field is `null` for text and image embeddings. | | `endSec` | `Optional` | The end time in seconds for this segment. This field is `null` for text and image embeddings. | | `startPageNumber` | `Optional` | The first page this embedding covers, counting from 1. The platform returns this field only for page-level embeddings of a PDF file, and `null` in every other case. | | `endPageNumber` | `Optional` | The last page this embedding covers, counting from 1 and including that page. This field matches the `startPageNumber` field when the embedding covers a single page. The platform returns this field only for page-level embeddings of a PDF file, and `null` in every other case. | #### EmbeddingUsage The `TwelvelabsApi.EmbeddingUsage` interface contains token counts for the request. Only Marengo 3.5 returns this object. | Name | Type | Description | | ------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `inputTokens` | `Record` | The number of tokens the request used. Each key names a type of content the request processed, and each value is the token count for that content. | | `truncated` | `boolean` | Whether the input was truncated to fit within the token limit. | #### EmbeddingTaskMediaMetadata The `TwelvelabsApi.EmbeddingTaskMediaMetadata` type provides metadata for the media input. The `inputType` field selects one variant: **Audio**: Metadata for audio embeddings. | Name | Type | Description | | ------------------ | ----------------------------------------------------------- | ------------------------------------------------------------ | | `inputType` | `"audio"` | The type of the input content. Value: `audio`. | | `inputUrl` | `Optional` | The publicly accessible URL for the audio file. | | `inputFilename` | `Optional` | The name of the audio file. | | `embeddingOptions` | `string[]` | The `embeddingOption` values used to generate the embedding. | | `embeddingScopes` | `TwelvelabsApi.EmbeddingAudioMetadataEmbeddingScopesItem[]` | The `embeddingScope` values used to generate the embedding. | | `duration` | `number` | The duration of the audio in seconds. | | `startOffsetSec` | `Optional` | The start offset in seconds. | | `endOffsetSec` | `Optional` | The end offset in seconds. | **Video**: Metadata for video embeddings. | Name | Type | Description | | ------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------- | | `inputType` | `"video"` | The type of the input content. Value: `video`. | | `inputUrl` | `Optional` | The publicly accessible URL for the video file. | | `inputFilename` | `Optional` | The name of the video file. | | `clipLength` | `Optional` | Length of each video clip in seconds. Only available for fixed segmentation. | | `embeddingScopes` | `TwelvelabsApi.EmbeddingVideoMetadataEmbeddingScopesItem[]` | The `embeddingScope` values used to generate the embedding. | | `embeddingOptions` | `string[]` | The `embeddingOption` values used to generate the embedding. | | `duration` | `number` | The duration of the video in seconds. | | `startOffsetSec` | `Optional` | The start offset in seconds. | | `endOffsetSec` | `Optional` | The end offset in seconds. | **Document**: Metadata for document embeddings. Only Marengo 3.5 returns this object. | Name | Type | Description | | ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ | | `inputType` | `"document"` | The type of the input content. Value: `document`. | | `inputUrl` | `Optional` | The publicly accessible URL for the document file. | | `inputFilename` | `Optional` | The name of the document file. | | `embeddingOptions` | `Optional` | The `embeddingOption` values used to generate the embedding. | | `embeddingScopes` | `Optional` | The `embeddingScope` values used to generate the embedding. | **Image**: Metadata for image embeddings. Only Marengo 3.5 returns this object. | Name | Type | Description | | ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `inputType` | `"image"` | The type of the input content. Value: `image`. | | `inputUrl` | `Optional` | The publicly accessible URL for the image file. | | `inputFilename` | `Optional` | The name of the image file. | | `embeddingOptions` | `Optional` | The `embeddingOption` values used to generate the embedding. Always `["visual"]`. | | `embeddingScopes` | `Optional` | The `embeddingScope` values used to generate the embedding. Always `["asset"]`. | The `TwelvelabsApi.EmbeddingTaskResponseError` interface contains the following property: | Name | Type | Description | | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | `string` | A human-readable message that describes why the task failed. Possible values: - "The embedding service is temporarily unstable. Please try again later." - "The embedding task failed. Please try again later." - "We could not process your media for embedding. Please verify the input file and try again." For the steps to fix the file, see the [How do I fix a file that could not be processed for embedding?](/v1.3/docs/resources/frequently-asked-questions#how-do-i-fix-a-file-that-could-not-be-processed-for-embedding) section on the **Frequently asked questions** page. | ### API Reference [Retrieve task status and results](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings) > Create embeddings asynchronously for audio, video, images, and documents.