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, video, or documents 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.
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
Your API key.
You can find your API key on the API Keys page.
Request
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>, wherenamematches thenamefield of a media source. Marengo 3.5 accepts images, video, audio, and documents 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.
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.
Controls the behavior of the platform when the text in your request exceeds 2,000 tokens. Requires Marengo 3.5.
Values:
false: The platform returns a400error.true: Truncate your text to fit the limit, and set theusage.truncatedfield totruein the response.
Set this parameter to true to include a per-dimension uncertainty vector in the data[].embedding_uncertainty field of the response. The vector has the same length as the embedding array. A higher value indicates lower confidence in that dimension. Requires Marengo 3.5.
Requirements:
- Set this parameter to
trueonly for a text-only or media-only request. If you combine text with media sources, the platform returns a400error. - The platform returns a
400error if your request includes a document, whether PDF, plain text, or Markdown.
The number of dimensions for each embedding in the response, 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.0returns a400error. - Applies to the entire request: you cannot set it for a single input type or embedding.
- Use the same value across an index.
Default: 512
This field is required if the input_type parameter is text.
This field is required if the input_type parameter is image. Requires Marengo 3.0. The decoded file can be up to 32 MB.
This field is required if the input_type parameter is text_image. Requires Marengo 3.0. The decoded file can be up to 32 MB.
This field is required if the input_type parameter is audio. Requires Marengo 3.0. The decoded file can be up to 36 MB.
This field is required if the input_type parameter is video. Requires Marengo 3.0. The decoded file can be up to 36 MB.
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, audio, and documents 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, if you combine an image and a video without text, the platform returns a 400 error. Media sources of the same type do not require text. If any source has no content to embed, the platform returns a 400 error.
Document sources
The platform embeds a plain text or Markdown document as text. Combining content into a single embedding requires at least one image, video, or audio source; if the content is all text, the platform returns a 400 error. A plain text or Markdown document combined with input_text, and two plain text documents, are both all-text content. Send a single text document as your only source, use input_text on its own, or add an image, video, or audio source.
A PDF document must be your only source. You cannot combine it with any other media source, including another document, or with input_text; the platform returns a 400 error if you do. To combine document content with an image, video, or audio source, send a plain text or Markdown document instead of a PDF file.
Response headers
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.
The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.
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.
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.
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.
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.
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.
Response
Metadata for the media input. Available for the image, text_image, audio, video, and multi_input input types.