embed > v2 > tasks

Create an async embedding task

Changed on

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 POST method of the /embed-v2 endpoint instead.

The content this method accepts depends on the model. Both models embed audio and video. Marengo 3.5 also embeds images and documents: PDF, plain text, and Markdown files. For the formats, resolutions, file sizes, and duration limits each model accepts, see the input requirements for Marengo 3.5 or Marengo 3.0.

Creating embeddings asynchronously requires three steps:

  1. Create a task using this method. The platform returns a task identifier.
  2. Poll for the status of the task using the GET 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 method of the /embed-v2/tasks/{task_id} endpoint.
<Note title="Notes"> - Creating a task validates only basic metadata and, for audio and video sources, 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 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/plans-and-billing/rate-limits/new-billing#input-token-limits-for-embedding). - Embeddings are stored for seven days. </Note>
post/embed-v2/tasks

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/embed-v2/tasks
  • Auth: API key in header x-api-key

Request body

input_type'audio' | 'video' | 'document' | 'image' required

The type of content for the embeddings.

Values:

  • audio: An audio file.
  • video: A video file.
  • document: A PDF, plain text, or Markdown file. Requires Marengo 3.5.
  • image: An image file. Requires Marengo 3.5.
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 page.
  • marengo3.0: For details about this version, see the Marengo 3.0 page.
embedding_uncertaintyboolean

Set this parameter to true to include a per-dimension uncertainty vector in the data[].embedding_uncertainty field of the result. The vector has the same length as the embedding array. A higher value indicates lower confidence in that dimension. Requires Marengo 3.5.

Requirements:

  • For audio or video input, set the embedding_scope field to exclude asset. For example, set the video.embedding_scope field to ["clip"]. The field defaults to ["clip", "asset"], so the platform returns a 400 error if you keep the default. This requirement does not apply to image input.
  • For a PDF document, the platform returns a 400 error regardless of the document.embedding_scope value.
  • For a plain text or Markdown document, set the document.embedding_scope field to ["local"]. Any other value returns a 400 error.
embedding_dimension'128' | '256' | '512'

The number of dimensions for each embedding that the task produces, including the data[].embedding_uncertainty vector.

Marengo 3.5 produces Matryoshka embeddings: a shorter embedding consists of the first values of the full-length embedding. A 256-dimension embedding, for example, is the first 256 values of a 512-dimension embedding of the same content. Shorter embeddings reduce index size and speed up similarity search; longer embeddings produce higher retrieval quality.

Requirements:

  • Requires Marengo 3.5. Setting this parameter with model_name: marengo3.0 returns a 400 error.
  • Applies to the entire task: you cannot set it for a single input type or embedding.
  • Set it once, when you create the task. To use a different value, create a new task.
  • Use the same value across an index.

Default: 512

Response

An embedding task has successfully been created.

_idstring required

The unique identifier of the embedding task

status'processing' required

The initial status of the embedding task.

Changes

  • 69c273061729Revision changes
    • warning

      added the new chunk enum value to the /// response property for the response status

    • info

      added the new optional request property /

    • info

      added the new optional request property

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

  • b8591e05c0baRevision changes
    • warning

      deleted the header request parameter x-api-key

    • info

      the endpoint scheme security x-api-key was added to the API