Sign in
embed > v2 > tasks

Create an async embedding task

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 PDF 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 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/rate-limits#input-token-limits-for-embedding). - Embeddings are stored for seven days. </Note>
post/embed-v2/tasks

Headers

x-api-keystring required

Your API key.

<Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

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 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 receive a 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.

To use this parameter with audio or video input, exclude the asset scope from the embedding_scope field. For example, set video.embedding_scope 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.

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