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

# Create sync embeddings

`POST /embed-v2`

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

**When to use this endpoint**:
- Create embeddings for text, images, audio, or video content
- Retrieve immediate results without waiting for background processing
- Process audio or video content up to 10 minutes in duration

**Do not use this endpoint for**:
- Audio or video content longer than 10 minutes. Use the [`POST`](/v1.3/api-reference/create-embeddings-v2/create-async-embedding-task) method of the `/embed-v2/tasks` endpoint instead.

<Accordion title="Input requirements">
  **Text**:
  - Maximum length: 500 tokens

  **Images**:
  - Formats: JPEG, PNG
  - Minimum size: 128x128 pixels
  - Maximum file size: 32 MB

  **Audio and video**:
  - Maximum duration: 10 minutes
  - Maximum file size for base64 encoded strings: 36 MB
  - Audio formats: WAV (uncompressed), MP3 (lossy), FLAC (lossless)
  - Video formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html)
  - Video resolution: 360x360 to 5184x2160 pixels
  - Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1
</Accordion>

<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Headers

- `x-api-key` string, required

## Request body

- CreateEmbeddingsRequest — Defines the embedding request. The required fields vary depending on the the value of the `input_type` parameter. For example, when `input_type` is `text`, the `text` field becomes mandatory.
  - `input_type` 'text' | 'image' | 'text_image' | 'audio' | 'video' | 'multi_input', required — The type of content for the embeddings. **Values**: - `audio`: Creates embeddings for an audio file - `video`: Creates embeddings for a video file - `image`: Creates embeddings for an image file - `text`: Creates embeddings for text input - `text_image`: Creates embeddings for text and an image - `multi_input`: Creates a single embedding from up to 10 images. You can optionally include text to provide context. To reference specific images in your text, use placeholders in the following format: `<@name>`, where `name` matches the `name` field of a media source
  - `model_name` 'marengo3.0', required — The video understanding model to use. Value: "marengo3.0".
  - `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 maximul 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.
      - `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.
      - `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 maximul 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.
      - `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. **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.
    - `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.
    - `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.
      - `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. **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. **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`.
    - `input_text` string — Text to combine with the images when generating the embedding. **Usage options**: - Omit this field to create an embedding from images only. - Provide plain text to add context. Example: "A person cooking." - Use image references to describe relationships between specific images. The format is `<@name>`, where `name` matches the `name` field of a media source. Example: "A person wearing <@outfit> and holding <@accessory>."
    - `media_sources` MultiInputMediaSource[], required — An array of up to 10 images to include in the embedding. The platform processes images in the order they appear in the array. If you use image 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 image with a matching `name` field. If an image reference has no match, the request fails.
      - `name` string — The unique identifier for this media source. This field is required when `input_type` references this image.
      - `media_type` 'image', required — The type of media. **Value**: `image`
      - `url` string, uri — The publicly accessible URL of the image file Use direct links to raw image files. Image hosting platforms and cloud storage sharing links are not supported.
      - `base64_string` string — The base64-encoded image 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`

Successful request; normal operation

- EmbeddingSuccessResponse
  - `data` EmbeddingData[], required — Array of embedding results
    - `embedding` number[], required — The embedding vector for the content.
    - `embedding_option` 'visual' | 'audio' | 'transcription' | 'fused' — The modality used to generate this embedding. **Values**: - `visual`: Embedding based on visual content (video only) - `audio`: Embedding based on audio content - `transcription`: Embedding based on transcribed speech - `fused`: Embedding based on a combination of the modalities specified in the request. The platform returns this embedding only for video and audio content, and only when the `embedding_type` parameter in the request includes `fused_embedding`. - `null`: For text and image embeddings
    - `embedding_scope` 'clip' | 'asset' — The scope for which the embedding was generated. **Values**: - `clip`: Embedding for a segment - `asset`: Embedding for the entire file. Use this scope for videos up to 10-30 seconds to maintain optimal performance. - `null`: For text and image embeddings
    - `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.
  - `metadata` union — Metadata for the media input. Available for image, text_image, audio, video, and multi_input inputs.
    - 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
      - `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
      - `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 — Audio embedding options used for generating the embedding
      - `embedding_scopes` EmbeddingAudioMetadataEmbeddingScopesItems[], required — Audio embedding scopes
      - `duration` number, double, required — Duration of the audio in seconds
      - `start_offset_sec` number, double — Start offset in seconds
      - `end_offset_sec` number, double — 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 — Video embedding scopes
      - `embedding_options` string[], required — Video embedding options used for generating the embedding
      - `duration` number, double, required — Duration of the video in seconds
      - `start_offset_sec` number, double — Start offset in seconds
      - `end_offset_sec` number, double — 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 artifact
- `429` — Client exceeded rate limits
- `500` — Unhandled edge or corner case

---

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