Skip to navigation
Models and searchCreate embeddings v2

Create sync embeddings

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

Use this method to embed a query for retrieving matching content. With Marengo 3.5, audio and video can be up to 30 seconds. With Marengo 3.0, they can be up to 10 minutes. For longer content, use the POST method of the /embed-v2/tasks endpoint instead.

The content this method accepts depends on the model. With Marengo 3.5, this method accepts only the multi_input input type; provide text, images, audio, or video as media sources. With Marengo 3.0, use the individual input types. For the formats, resolutions, file sizes, and duration limits each model accepts, see the input requirements for Marengo 3.5 or Marengo 3.0.

Note

This method is rate-limited. With Marengo 3.5, the platform counts input tokens for each type of content. A request can exceed a limit before you see an error. For details, see Input token limits for embedding.

Authentication

x-api-keystring

Your API key.

Note

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

Request

This endpoint expects an object.
input_typeenumRequired

The type of content for the embeddings.

Values:

  • multi_input: Text and up to 10 media sources, combined into a single embedding. To reference a specific media source from your text, use a placeholder in the following format: <@name>, where name matches the name field of a media source. Marengo 3.5 accepts images, video, and audio as media sources. Marengo 3.0 accepts images.
  • audio: An audio file. Requires Marengo 3.0.
  • video: A video file. Requires Marengo 3.0.
  • image: An image file. Requires Marengo 3.0.
  • text: Text input. Requires Marengo 3.0.
  • text_image: Text and an image. Requires Marengo 3.0.
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.
Allowed values:
auto_truncatebooleanOptionalDefaults to false

Controls the behavior of the platform when the text in your request exceeds 2,000 tokens. Requires Marengo 3.5.

Values:

  • false: Return a 400 error.
  • true: Truncate your text to fit the limit, and set the usage.truncated field to true in the response.
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.

Set this parameter to true only when your request embeds text only, or media only. Requests that combine text with media sources return a 400 error.

textobjectOptional

This field is required if the input_type parameter is text.

imageobjectOptional

This field is required if the input_type parameter is image.

text_imageobjectOptional

This field is required if the input_type parameter is text_image.

audioobjectOptional

This field is required if the input_type parameter is audio.

videoobjectOptional

This field is required if the input_type parameter is video.

multi_inputobjectOptional

This field is required if the input_type parameter is multi_input. It combines text and up to 10 media sources into a single embedding. Provide the input_text field, the media_sources field, or both.

Marengo 3.5 accepts images, video, and audio as media sources. Marengo 3.0 accepts images.

Include text in the input_text field when you combine media sources of different types. For example, a request that combines an image and a video returns a 400 error without text. Media sources of the same type do not require text.

Response headers

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.

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
The maximum number of input tokens per rate limit window for the type of content named in this header.
X-Ratelimit-Inputtoken-Video-Remaininginteger

The number of input tokens remaining in the current rate limit window for the type of content named in this header. A synchronous response already counts the tokens the request used. This value can be 0 on a response that succeeded. A 202 response does not yet count the task you submitted.

X-Ratelimit-Inputtoken-Video-Resetinteger
The time at which the current input token rate limit window resets for the type of content named in this header, expressed in UTC epoch seconds.
X-Ratelimit-Inputtoken-Audio-Limitinteger
The maximum number of input tokens per rate limit window for the type of content named in this header.
X-Ratelimit-Inputtoken-Audio-Remaininginteger

The number of input tokens remaining in the current rate limit window for the type of content named in this header. A synchronous response already counts the tokens the request used. This value can be 0 on a response that succeeded. A 202 response does not yet count the task you submitted.

X-Ratelimit-Inputtoken-Audio-Resetinteger
The time at which the current input token rate limit window resets for the type of content named in this header, expressed in UTC epoch seconds.
X-Ratelimit-Inputtoken-Image-Limitinteger
The maximum number of input tokens per rate limit window for the type of content named in this header.
X-Ratelimit-Inputtoken-Image-Remaininginteger

The number of input tokens remaining in the current rate limit window for the type of content named in this header. A synchronous response already counts the tokens the request used. This value can be 0 on a response that succeeded. A 202 response does not yet count the task you submitted.

X-Ratelimit-Inputtoken-Image-Resetinteger
The time at which the current input token rate limit window resets for the type of content named in this header, expressed in UTC epoch seconds.
X-Ratelimit-Inputtoken-Document-Limitinteger
The maximum number of input tokens per rate limit window for the type of content named in this header.
X-Ratelimit-Inputtoken-Document-Remaininginteger

The number of input tokens remaining in the current rate limit window for the type of content named in this header. A synchronous response already counts the tokens the request used. This value can be 0 on a response that succeeded. A 202 response does not yet count the task you submitted.

X-Ratelimit-Inputtoken-Document-Resetinteger
The time at which the current input token rate limit window resets for the type of content named in this header, expressed in UTC epoch seconds.
X-Ratelimit-Inputtoken-Text-Limitinteger
The maximum number of input tokens per rate limit window for the type of content named in this header.
X-Ratelimit-Inputtoken-Text-Remaininginteger

The number of input tokens remaining in the current rate limit window for the type of content named in this header. A synchronous response already counts the tokens the request used. This value can be 0 on a response that succeeded. A 202 response does not yet count the task you submitted.

X-Ratelimit-Inputtoken-Text-Resetinteger
The time at which the current input token rate limit window resets for the type of content named in this header, expressed in UTC epoch seconds.

Response

The embeddings have been successfully created.
datalist of objects
Array of embedding results
usageobjectOptional
Token counts for the request. Only Marengo 3.5 returns this field.
metadataobjectOptional

Metadata for the media input. Available for the image, text_image, audio, video, and multi_input input types.

Errors

400
Bad Request Error
429
Too Many Requests Error
500
Internal Server Error