---
title: "Create an async embedding task"
method: POST
path: "/embed-v2/tasks"
tags: ["embed > v2 > tasks"]
---

# Create an async embedding task

`POST /embed-v2/tasks`

This endpoint creates embeddings for audio and video content asynchronously.

**When to use this endpoint**:
- Process audio or video files longer than 10 minutes
- Process files up to 4 hours in duration

<Accordion title="Input requirements">
  **Video**:
  - Minimum duration: 4 seconds
  - Maximum duration: 4 hours
  - Maximum file size: 4 GB
  - Formats: [FFmpeg supported formats](https://ffmpeg.org/ffmpeg-formats.html)
  - Resolution: 360x360 to 5184x2160 pixels
  - Aspect ratio: Between 1:1 and 1:2.4, or between 2.4:1 and 1:1

  **Audio**:
  - Minimum duration: 4 seconds
  - Maximum duration: 4 hours
  - Maximum file size: 4 GB
  - Formats: WAV (uncompressed), MP3 (lossy), FLAC (lossless)
</Accordion>

  Creating embeddings asynchronously requires three steps:

  1. Create a task using this endpoint. The platform returns a task ID.
  2. Poll for the status of the task using the [`GET`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings) method of the `/embed-v2/tasks/{task_id}` endpoint. Wait until the status is `ready`.
  3. Retrieve the embeddings from the response when the status is `ready` using the [`GET`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings) method of the `/embed-v2/tasks/{task_id}` endpoint.

  <Note title="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`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings#response.body.status) field. If it is `failed`, the [`error.message`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings#response.body.error.message) field contains the reason.
  - This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
  - Embeddings are stored for seven days.
  </Note>

## Headers

- `x-api-key` string, required

## Request body

- CreateAsyncEmbeddingRequest — Defines the asynchronous embedding request. The required fields vary depending on the value of the `input_type` parameter. When `input_type` is `audio`, the `audio` field is required. When `input_type` is `video`, the `video` field is required.
  - `input_type` 'audio' | 'video', required — The type of content for the embeddings. **Values**: - `audio`: Audio files - `video`: Video content
  - `model_name` 'marengo3.0', required — The model you wish to use. Value: `"marengo3.0"`.
  - `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`.

## Response `202`

An embedding task has successfully been created.

- EmbedV2TasksCreateResponse202
  - `_id` string, required — The unique identifier of the embedding task
  - `status` 'processing', required — The initial status of the embedding task.
  - `data` EmbeddingData[], nullable — An array of embedding results when `status` is `ready`, or `null` when `status` is `processing` or `failed`.
    - `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.

## Other responses

- `400` — Validation failure or inaccessible artifact
- `500` — Internal server error

---

[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)