---
title: "Create sync embeddings"
method: POST
path: "/embed-v2"
tags: ["embed > v2"]
---

# Create sync embeddings

`POST /embed-v2`

This method synchronously creates embeddings for multimodal content and returns the results immediately in the response.

Use this method to embed a query for retrieving matching content. With Marengo 3.5, audio and video can be up to 30 seconds. With Marengo 3.0, they can be up to 10 minutes. For longer content, use the [`POST`](/v1.3/api-reference/create-embeddings-v2/create-async-embedding-task) method of the `/embed-v2/tasks` endpoint instead.

The content this method accepts depends on the model. With Marengo 3.5, this method accepts only the `multi_input` input type; provide text, images, audio, or video as media sources. With Marengo 3.0, use the individual input types. 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).

<Note title="Note">
This method is rate-limited. With Marengo 3.5, the platform counts input tokens for each type of content. A request 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).
</Note>

## Headers

- `x-api-key` string, required

## Request body

- CreateEmbeddingsRequest — Defines the embedding request. Set the `input_type` parameter to the kind of content you are embedding, and provide the field with the same name.
  - `input_type` 'text' | 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required — The type of content for the embeddings. **Values**: - `multi_input`: Text and up to 10 media sources, combined into a single embedding. To reference a specific media source from your text, use a placeholder in the following format: `<@name>`, where `name` matches the `name` field of a media source. Marengo 3.5 accepts images, video, and audio as media sources. Marengo 3.0 accepts images. - `audio`: An audio file. Requires Marengo 3.0. - `video`: A video file. Requires Marengo 3.0. - `image`: An image file. Requires Marengo 3.0. - `text`: Text input. Requires Marengo 3.0. - `text_image`: Text and an image. Requires Marengo 3.0.
  - `model_name` 'marengo3.0' | 'marengo3.5', required — 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.
  - `auto_truncate` boolean — Controls the behavior of the platform when the text in your request exceeds 2,000 tokens. Requires Marengo 3.5. **Values**: - `false`: Return a `400` error. - `true`: Truncate your text to fit the limit, and set the [`usage.truncated`](/v1.3/api-reference/create-embeddings-v2/create-embeddings#response.body.usage.truncated) field to `true` in the response.
  - `embedding_uncertainty` boolean — Set this parameter to `true` to receive a [`data[].embedding_uncertainty`](/v1.3/api-reference/create-embeddings-v2/create-embeddings#response.body.data.embedding-uncertainty) 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. Set this parameter to `true` only when your request embeds text only, or media only. Requests that combine text with media sources return a `400` error.
  - `text` TextInputRequest — This field is required if the `input_type` parameter is `text`.
    - `input_text` string, required — The text for which you wish to create an embedding. The maximum length is 500 tokens.
  - `image` ImageInputRequest — This field is required if the `input_type` parameter is `image`.
    - `media_source` MediaSource, required — An object specifying the source of the media file. You must provide exactly one of `url`, `base64_string`, or `asset_id`.
      - `base64_string` string — The base64-encoded media data. The decoded file can be up to 36 MB; encoded, it can be up to 48 MB.
      - `url` string, uri — 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.
      - `asset_id` string — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
  - `text_image` TextImageInputRequest — This field is required if the `input_type` parameter is `text_image`.
    - `media_source` MediaSource, required — An object specifying the source of the media file. You must provide exactly one of `url`, `base64_string`, or `asset_id`.
      - `base64_string` string — The base64-encoded media data. The decoded file can be up to 36 MB; encoded, it can be up to 48 MB.
      - `url` string, uri — 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.
      - `asset_id` string — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - `input_text` string, required — The text for which you wish to create an embedding. The maximum length is 500 tokens.
  - `audio` AudioInputRequest — This field is required if the `input_type` parameter is `audio`.
    - `media_source` MediaSource, required — An object specifying the source of the media file. You must provide exactly one of `url`, `base64_string`, or `asset_id`.
      - `base64_string` string — The base64-encoded media data. The decoded file can be up to 36 MB; encoded, it can be up to 48 MB.
      - `url` string, uri — 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.
      - `asset_id` string — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - `start_sec` number, double — 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).
    - `end_sec` number, double — 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` AudioSegmentation — Specifies how the platform divides the audio into segments.
      - `strategy` 'fixed', required
      - `fixed` AudioSegmentationFixed, required — Configuration for fixed segmentation. This object is required when the `strategy` field is `fixed`.
        - `duration_sec` integer, required — 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].
    - `embedding_option` AudioInputRequestEmbeddingOptionItems[] — The types of embeddings you wish to generate. **Values**: - `audio`: Generates embeddings based on audio content (sounds, music, effects) - `transcription`: Generates embeddings based on transcribed speech You can specify multiple values to generate different types of embeddings for the same audio. **Default**: `["audio", "transcription"]`
    - `embedding_scope` AudioInputRequestEmbeddingScopeItems[] — The scope for which you wish to generate embeddings. **Values**: - `clip`: Generates one embedding for each segment - `asset`: Generates one embedding for the entire audio file You can specify multiple scopes to generate embeddings at different levels. **Default**: `["clip", "asset"]`
    - `embedding_type` AudioInputRequestEmbeddingTypeItems[] — Specifies how to structure the embedding. Include this parameter only when the `embedding_option` parameter contains at least two values. **Values**: - `separate_embedding`: Returns separate embeddings for each modality specified in the `embedding_option` parameter. - `fused_embedding`: Returns a single combined embedding that integrates all modalities into one vector. Specify both values to receive separate and fused embeddings in the same response. **Default**: `separate_embedding`.
  - `video` VideoInputRequest — This field is required if the `input_type` parameter is `video`.
    - `media_source` MediaSource, required — An object specifying the source of the media file. You must provide exactly one of `url`, `base64_string`, or `asset_id`.
      - `base64_string` string — The base64-encoded media data. The decoded file can be up to 36 MB; encoded, it can be up to 48 MB.
      - `url` string, uri — 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.
      - `asset_id` string — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content/direct-uploads) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) method to check the status.
    - `start_sec` number, double — 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)
    - `end_sec` number, double — 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` union — Specifies how the platform divides the video into segments. The `strategy` field selects one variant: - `strategy: fixed` - Creates segments of equal, predetermined length. Use this for consistent timing. - `strategy: dynamic` - Creates segments of variable length that align with scene boundaries. Use this for content-aware segmentation.
      - object — Divides the video into segments of variable length that align with scene boundaries. Use this for content-aware segmentation.
        - `strategy` 'dynamic', required — Discriminator value: dynamic
        - `dynamic` VideoSegmentationDiscriminatorMappingDynamicDynamic, required — Configuration for dynamic segmentation. This object is required when `strategy` is `dynamic`.
          - `min_duration_sec` integer, required — 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]
      - object — Divides the video into segments of equal, predetermined length. Use this for consistent timing.
        - `strategy` 'fixed', required — Discriminator value: fixed
        - `fixed` VideoSegmentationDiscriminatorMappingFixedFixed, required — Configuration for fixed segmentation. This object is required when `strategy` is `fixed`.
          - `duration_sec` integer, required — 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].
    - `embedding_option` VideoInputRequestEmbeddingOptionItems[] — 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) - `transcription`: Generates embeddings based on transcribed speech You can specify multiple values to generate different types of embeddings for the same video. **Default**: `["visual", "audio", "transcription"]`
    - `embedding_scope` VideoInputRequestEmbeddingScopeItems[] — The scope for which you wish to generate embeddings. **Values**: - `clip`: Generates one embedding for each segment - `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"]`
    - `embedding_type` VideoInputRequestEmbeddingTypeItems[] — Specifies how to structure the embedding. Include this parameter only when `embedding_option` contains at least two values. **Values**: - `separate_embedding`: Returns separate embeddings per modality specified in `embedding_option` - `fused_embedding`: Returns a single embedding that combines all modalities into one vector Specify both values to receive separate and fused embeddings in the same response. **Default**: `separate_embedding`.
  - `multi_input` MultiInputRequest — This field is required if the `input_type` parameter is `multi_input`. It combines text and up to 10 media sources into a single embedding. Provide the `input_text` field, the `media_sources` field, or both. Marengo 3.5 accepts images, video, and audio as media sources. Marengo 3.0 accepts images. Include text in the `input_text` field when you combine media sources of different types. For example, a request that combines an image and a video returns a `400` error without text. Media sources of the same type do not require text. With Marengo 3.5, the text cannot exceed 2,000 tokens. Media sources do not count toward this limit. Use the `auto_truncate` parameter to control the behavior of the platform when your text exceeds it.
    - `input_text` string — Text to include in the embedding. **Usage options**: - Provide text without media sources to create a text-only embedding. - Combine text with media sources to add context. Example: "A person cooking." - Use media source references to describe relationships between specific media sources. The format is `<@name>`, where `name` matches the `name` field of a media source. Example: "A person wearing <@outfit> and holding <@accessory>." - Omit this field to create an embedding from media sources only.
    - `media_sources` MultiInputMediaSource[] — An array of up to 10 media sources to include in the embedding. Omit it to create a text-only embedding from the `input_text` field. The platform processes media sources in the order they appear in the array. If you use media source references in the [`input_text`](/v1.3/api-reference/create-embeddings-v2/create-embeddings#request.body.multi_input.input_text) parameter, each must have a corresponding media source with a matching `name` field. If a reference has no match, the request fails.
      - `name` string — The unique identifier for this media source. This field is required when `input_text` references this media source.
      - `media_type` 'image' | 'video' | 'audio', required — The type of media. **Values**: - `image`: An image file. Works with both Marengo 3.0 and Marengo 3.5. - `video`: A video file. Requires Marengo 3.5. - `audio`: An audio file. Requires Marengo 3.5.
      - `url` string, uri — The publicly accessible URL of the media file. Use direct links to raw files. Media hosting platforms and cloud storage sharing links are not supported.
      - `base64_string` string — The base64-encoded media data.
      - `asset_id` string — The unique identifier of an asset from a [direct](/v1.3/api-reference/upload-content) or [multipart](/v1.3/api-reference/upload-content/multipart-uploads) upload.

## Response `200`

The embeddings have been successfully created.

- EmbeddingSuccessResponse
  - `data` EmbeddingData[], required — Array of embedding results
    - `embedding` number[], required — The embedding vector for the content.
    - `embedding_uncertainty` number[] — 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 [`embedding_uncertainty: true`](/v1.3/api-reference/create-embeddings-v2/create-embeddings#request.body.embedding-uncertainty). Only Marengo 3.5 returns this field.
    - `embedding_option` 'visual' | 'audio' | 'transcription' | 'text' | 'fused' — 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. - `text`: The platform does not return this value. - `transcription`: Embedding based on transcribed speech. Returned only for content embedded with Marengo 3.0. - `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 `embedding_type` parameter includes the `fused_embedding` value. - `null`: For text embeddings and images embedded synchronously.
    - `embedding_scope` 'clip' | 'page' | 'asset' — 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.embedding_scopes` field contains the scopes you requested.
    - `start_sec` number, double, nullable — The start time in seconds for this segment. This field is `null` for text and image embeddings.
    - `end_sec` number, double, nullable — The end time in seconds for this segment. This field is `null` for text and image embeddings.
    - `start_page_number` integer, nullable — 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.
    - `end_page_number` integer, nullable — The last page this embedding covers, counting from 1 and including that page. This field matches the `start_page_number` 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.
  - `usage` EmbeddingUsage — Token counts for the request. Only Marengo 3.5 returns this object.
    - `input_tokens` object, required — 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, required — Whether the input was truncated to fit within the token limit.
  - `metadata` union — Metadata for the media input. Available for the `image`, `text_image`, `audio`, `video`, and `multi_input` input types.
    - object — Metadata for image embeddings.
      - `input_type` 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required
      - `input_url` string — The publicly accessible URL for the image file.
      - `input_filename` string — The name of the image file.
    - object — Metadata for text-image embeddings.
      - `input_type` 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required
      - `input_url` string — The publicly accessible URL for the image file.
      - `input_filename` string — The name of the image file.
    - object — Metadata for audio embeddings.
      - `input_type` 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required
      - `input_url` string — The publicly accessible URL for the audio file.
      - `input_filename` string — The name of the audio file.
      - `embedding_options` string[], required — The `embedding_option` values used to generate the embedding.
      - `embedding_scopes` EmbeddingAudioMetadataEmbeddingScopesItems[], required — The `embedding_scope` values used to generate the embedding.
      - `duration` number, double, required — The duration of the audio in seconds.
      - `start_offset_sec` number, double — The start offset in seconds.
      - `end_offset_sec` number, double — The end offset in seconds.
    - object — Metadata for video embeddings.
      - `input_type` 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required
      - `input_url` string — The publicly accessible URL for the video file.
      - `input_filename` string — The name of the video file.
      - `clip_length` integer — Length of each video clip in seconds. Only available for fixed segmentation.
      - `embedding_scopes` EmbeddingVideoMetadataEmbeddingScopesItems[], required — The `embedding_scope` values used to generate the embedding.
      - `embedding_options` string[], required — The `embedding_option` values used to generate the embedding.
      - `duration` number, double, required — The duration of the video in seconds.
      - `start_offset_sec` number, double — The start offset in seconds.
      - `end_offset_sec` number, double — The end offset in seconds.
    - object — Metadata for multi-input embeddings.
      - `input_type` 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required

## Other responses

- `400` — Validation failure or inaccessible asset
- `429` — You have exceeded a rate limit, and the platform has not processed the request. For an asynchronous submission, no task has been created. For an input token limit, an earlier request exceeds it. That request completes normally, returning its embeddings or finishing as a task. The platform returns the error for the requests that follow. The `X-Ratelimit-Dimensions` header lists the limits the request was checked against. The `Retry-After` header contains the number of seconds to wait.
- `500` — Internal server error.

## Changes

- **2026-09-01** `8bb2e6eb62e8` — 2 breaking, 2 warning, 15 info
  - removed `subschema #1, subschema #2` from the `video/segmentation` request property `oneOf` list
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5` to the `metadata` response property `oneOf` list for the response status `200`
  - added the new `page` enum value to the `data/items/embedding_scope/oneOf[subschema #1: EmbeddingDataEmbeddingScope]/` response property for the response status `200`
  - added the new `text` enum value to the `data/items/embedding_option/oneOf[subschema #1: EmbeddingDataEmbeddingOption]/` response property for the response status `200`
  - …15 more
- **2026-08-22** `fd9d80e384a8` — 8 breaking, 4 warning, 1 info
  - the `audio/media_source/base64_string` request property's minLength was increased from `0` to `1`
  - the `image/media_source/base64_string` request property's minLength was increased from `0` to `1`
  - the `multi_input/media_sources/items/base64_string` request property's minLength was increased from `0` to `1`
  - the `text/input_text` request property's minLength was increased from `0` to `1`
  - …9 more
- **2026-08-12** `b6d766c2c340` — 1 breaking, 2 info
  - the `video/segmentation` request property type changed from `object` to no type
  - added discriminator to `video/segmentation` request property
  - added `subschema #1, subschema #2` to the `video/segmentation` request property `oneOf` list
- …earlier changes not shown

[Full history](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/changes/embed-v2/post.md)

---

[API](https://skmtc.dev/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/8bb2e6eb62e8/schema)