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:

Create a task using this method. The platform returns a task identifier.
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.
Retrieve the embeddings from the response when the status is ready using the GET method of the /embed-v2/tasks/{task_id} endpoint.

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 field. If it is failed, the 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.
Embeddings are stored for seven days.

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`](/v1.3/api-reference/create-embeddings-v2/create-embeddings) 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](/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). 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`](/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 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>

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

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

This endpoint expects an object.

input_typeenumRequired

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_nameenumRequiredDefaults to marengo3.0

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_uncertaintybooleanOptionalDefaults to false

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.

audioobjectOptional

This field is required if the input_type parameter is audio.

videoobjectOptional

This field is required if the input_type parameter is video.

documentobjectOptional

This field is required if the input_type parameter is document. Requires Marengo 3.5.

The platform embeds the rendered pages of your PDF file, one embedding per page.

imageobjectOptional

This field is required if the input_type parameter is image. Requires Marengo 3.5. The image can be up to 32 MB before encoding, whether you provide a URL, an asset identifier, or base64-encoded data. For an image, the embedding_option, embedding_type, and embedding_scope fields each accept a single value; any other value returns a 400 error.

Response headers

LocationstringOptional

URL to poll for task status and results

X-Ratelimit-DimensionsstringOptional

A comma-separated, alphabetically sorted list of the rate limits the request was measured against. Only the limits that applied to the request appear.

Each entry is a label. Replace <label> with an entry to read the values for that limit: X-Ratelimit-<label>-Limit, X-Ratelimit-<label>-Remaining, and X-Ratelimit-<label>-Reset. This list keeps the mixed-case spelling of each label, such as InputToken-Video. The platform sends the headers as X-Ratelimit-Inputtoken-Video-Limit. HTTP header names are case-insensitive, so the two spellings match.

The /embed-v2 and /embed-v2/tasks endpoints report every limit through this family. They do not send the aggregate X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Used, or X-Ratelimit-Reset headers that other endpoints send.

A comma-separated, alphabetically sorted list of the rate limits the request was measured against. Only the limits that applied to the request appear. Each entry is a label. Replace `<label>` with an entry to read the values for that limit: `X-Ratelimit-<label>-Limit`, `X-Ratelimit-<label>-Remaining`, and `X-Ratelimit-<label>-Reset`. This list keeps the mixed-case spelling of each label, such as `InputToken-Video`. The platform sends the headers as `X-Ratelimit-Inputtoken-Video-Limit`. HTTP header names are case-insensitive, so the two spellings match. The `/embed-v2` and `/embed-v2/tasks` endpoints report every limit through this family. They do not send the aggregate `X-Ratelimit-Limit`, `X-Ratelimit-Remaining`, `X-Ratelimit-Used`, or `X-Ratelimit-Reset` headers that other endpoints send.

X-Ratelimit-Request-Limitinteger

The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.

X-Ratelimit-Request-Remaininginteger

The number of requests remaining in the current rate limit window for this endpoint.

X-Ratelimit-Request-Resetinteger

The time at which the current request rate limit window resets, expressed in UTC epoch seconds.

X-Ratelimit-Inputtoken-Video-Limitinteger