openapi: 3.1.0 info: title: Voyage API description: > The VoyageAI REST API. Please see https://docs.voyageai.com/reference for more details. version: '1.1' contact: name: VoyageAI Support url: https://docs.voyageai.com/docs/faq email: contact@voyageai.com license: name: MIT url: https://github.com/voyage-ai/voyage-openapi/blob/main/LICENSE servers: - url: https://api.voyageai.com/v1 components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: 'Authorization: Bearer' x-default: $VOYAGE_API_KEY security: - ApiKeyAuth: [] tags: - name: Endpoints paths: /embeddings: post: tags: - Endpoints summary: Embeddings description: Voyage embedding endpoint receives as input a string (or a list of strings) and other arguments such as the preferred model name, and returns a response containing a list of embeddings. operationId: embeddings-api requestBody: content: application/json: schema: type: object required: - input - model properties: input: type: object description: > A single text string, or a list of texts as a list of strings. Currently, we have two constraints on the list:

The maximum length of the list is 128.
The total number of tokens in the list is at most 320K for `voyage-2`, and 120K for `voyage-large-2`, `voyage-finance-2`, `voyage-multilingual-2`, `voyage-law-2`, and `voyage-code-2`.

If `true`, over-length input texts will be truncated to fit within the context length, before vectorized by the embedding model.
If `false`, an error will be raised if any given text exceeds the context length.

If not specified (defaults to `null`): the embeddings are represented as lists of floating-point numbers;
`base64`: the embeddings are compressed to [base64](https://docs.python.org/3/library/base64.html) encodings.

This indicates an issue with the request format or frequency. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

This indicates our servers are experiencing high traffic or having an unexpected issue. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

The number of documents cannot exceed 1000.
The sum of the number of tokens in the query and the number of tokens in any single document cannot exceed 4000 for `rerank-lite-1` and 8000 for `rerank-1`.
he total number of tokens, defined as "the number of query tokens × the number of documents + sum of the number of tokens in all documents", cannot exceed 300K for `rerank-lite-1` and 100K for `rerank-1`. Please see our FAQ.

If `false`, the API will return a list of {"index", "relevance_score"} where "index" refers to the index of a document within the input list.
If `true`, the API will return a list of {"index", "document", "relevance_score"} where "document" is the corresponding document from the input list.

If `true`, the query and documents will be truncated to fit within the context length limit, before processed by the reranker model.
If `false`, an error will be raised when the query exceeds 1000 tokens for `rerank-lite-1` and 2000 tokens for `rerank-1`, or the sum of the number of tokens in the query and the number of tokens in any single document exceeds 4000 for `rerank-lite-1` and 8000 for `rerank-1`.

This indicates an issue with the request format or frequency. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

This indicates our servers are experiencing high traffic or having an unexpected issue. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

The value of "content" is a list of dictionaries, each representing a single piece of text or image. The dictionaries have four possible keys:
1. type: Specifies the type of the piece of the content. Allowed values are text, image_url, or image_base64.
2. text: Only present when type is text. The value should be a text string.
3. image_base64: Only present when type is image_base64. The value should be a Base64-encoded image in the data URL format data:[<mediatype>];base64,<data>. Currently supported mediatypes are: image/png, image/jpeg, image/webp, and image/gif.
4. image_url: Only present when type is image_url. The value should be a URL linking to the image. We support PNG, JPEG, WEBP, and GIF images.

Note: Only one of the keys, image_base64 or image_url, should be present in each dictionary for image data. Consistency is required within a request, meaning each request should use either image_base64 or image_url exclusively for images, not both.

Example payload where inputs contains an image as a URL

The inputs list contains a single input, which consists of a piece of text and an image (which is provided via a URL).


                          {
                            "inputs": [
                              {   
                                "content": [
                                  {   
                                    "type": "text",
                                    "text": "This is a banana."
                                  },  
                                  {   
                                    "type": "image_url",
                                    "image_url": "https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana.jpg"
                                  }   
                                ]   
                              }   
                            ],  
                            "model": "voyage-multimodal-3"
                          }

Example payload where inputs contains a Base64 image

Below is an equivalent example to the one above where the image content is a Base64 image instead of a URL. (Base64 images can be lengthy, so the example only shows a shortened version.)

  
                          {
                            "inputs": [
                              {   
                                "content": [
                                  {   
                                    "type": "text",
                                    "text": "This is a banana."
                                  },  
                                  {   
                                    "type": "image_base64",
                                    "image_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
                                  }   
                                ]   
                              }   
                            ],  
                            "model": "voyage-multimodal-3"
                          }

];base64,`. Currently supported mediatypes are: `image/png`, `image/jpeg`, `image/webp`, and `image/gif`. image_url: type: string description: > Only present when `type` is `image_url`. The value should be a URL linking to the image. We support PNG, JPEG, WEBP, and GIF images. model: type: string description: > Name of the model. Currently, the only supported model is `voyage-multimodal-3`. input_type: type: string description: > Type of the input text. Defaults to `null`. Other options: `query`, `document`.

When input_type is null, the embedding model directly converts your input data into numerical vectors. For retrieval/search purposes—where an input (called a "query") is used to search for relevant pieces of information (referred to as "documents")—we recommend specifying whether your inputs are intended as queries or documents by setting input_type to query or document, respectively. In these cases, Voyage prepends a prompt to your input before vectorizing it, helping the model create more effective vectors tailored for retrieval/search tasks. Since inputs can be multimodal, queries and documents can be text, images, or an interleaving of both modalities. Embeddings generated with and without the input_type argument are compatible.
For transparency, the following prompts are prepended to your input.

For query, the prompt is "Represent the query for retrieving supporting documents: ".
For document, the prompt is "Represent the query for retrieving supporting documents: ".

enum: - query - document truncation: type: boolean description: > Whether to truncate the input texts to fit within the context length. Defaults to `true`.

If `true`, over-length input texts will be truncated to fit within the context length, before vectorized by the embedding model.
If `false`, an error will be raised if any given text exceeds the context length.

encoding_format: type: string description: > Format in which the embeddings are encoded. We support two options:

If not specified (defaults to `null`): the embeddings are represented as lists of floating-point numbers;
`base64`: the embeddings are compressed to [base64](https://docs.python.org/3/library/base64.html) encodings.

enum: - base64 responses: '200': description: Success content: application/json: schema: properties: object: type: string description: The object type, which is always "list". data: type: array description: An array of embedding objects. items: type: object properties: object: type: string description: The object type, which is always "embedding". embedding: type: array description: > The embedding vector consists of a list of floating-point numbers. The length of this vector varies depending on the specific model. items: type: number index: type: integer description: > An integer representing the index of the embedding within the list of embeddings. model: type: string description: Name of the model. usage: type: object properties: total_tokens: type: integer description: The total number of tokens used for computing the embeddings. examples: Success: value: > { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.027587891, -0.021240234, 0.018310547, "...", -0.021240234 ], "index": 0 } ], "model": "voyage-multimodal-3", "usage": { "text_tokens": 5, "image_pixels": 2000000, "total_tokens": 3576 } } '4XX': description: > Client error

This indicates an issue with the request format or frequency. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

content: application/json: schema: properties: detail: type: string description: The error message. '5XX': description: > Server Error

This indicates our servers are experiencing high traffic or having an unexpected issue. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide.

x-readme: code-samples: - language: shell code: |- curl -X POST https://api.voyageai.com/v1/multimodalembeddings \ -H "Authorization: Bearer $VOYAGE_API_KEY" \ -H "content-type: application/json" \ -d ' { "inputs": [ { "content": [ { "type": "text", "text": "This is a banana." }, { "type": "image_url", "image_url": "https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana.jpg" } ] } ], "model": "voyage-multimodal-3" }' samples-languages: - shell x-readme: headers: [] explorer-enabled: false proxy-enabled: false samples-enabled: true x-readme-fauxas: true