---
title: "Text embedding models"
method: POST
path: "/embeddings"
tags: ["Inference"]
---

# Text embedding models

`POST /embeddings`

The Voyage text 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.

## Request body

- object
  - `model` string, required — Name of the model. Recommended options: `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-code-3`, `voyage-finance-2`, `voyage-law-2`.
  - `input_type` 'null' | 'query' | 'document', nullable — Type of the input text. Defaults to `null`. Other options: `query`, `document`. <ul> <li> When `input_type` is `null`, the embedding model directly converts the inputs into numerical vectors. For retrieval/search purposes, where a "query" is used to search for relevant information among a collection of data 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 automatically prepends a prompt to your `inputs` before vectorizing them, creating vectors more tailored for retrieval/search tasks. Embeddings generated with and without the `input_type` argument are compatible. </li> <li> For transparency, the following prompts are prepended to your input. </li> <ul> <li> For <code>query</code>, the prompt is <i>"Represent the query for retrieving supporting documents: ".</i> </li> <li> For <code>document</code>, the prompt is <i>"Represent the document for retrieval: ".</i> </li> </ul> <ul> <ul>
  - `truncation` boolean — Whether to truncate the input texts to fit within the context length. Defaults to `true`. <ul> <li> If `true`, an over-length input texts will be truncated to fit within the context length, before vectorized by the embedding model. </li> <li> If `false`, an error will be raised if any given text exceeds the context length. </li> </ul>
  - `output_dimension` integer, nullable — The number of dimensions for resulting output embeddings. Defaults to `null`. <ul> <li> Most models only support a single default dimension, used when `output_dimension` is set to `null` (see output embedding dimensions <a href="https://docs.voyageai.com/docs/embeddings" target="_blank">here</a>). </li> <li> `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-3-large`, `voyage-3.5`, and `voyage-3.5-lite`, and `voyage-code-3` support the following `output_dimension` values: 2048, 1024 (default), 512, and 256. </li> </ul>
  - `output_dtype` 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary' — The data type for the embeddings to be returned. Defaults to `float`. Other options: `int8`, `uint8`, `binary`, `ubinary`. `float` is supported for all models. `int8`, `uint8`, `binary`, and `ubinary` are supported by `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-3-large`, `voyage-3.5`, and `voyage-3.5-lite`, and `voyage-code-3`. Please see our <a href="https://docs.voyageai.com/docs/flexible-dimensions-and-quantization#quantization" target="_blank">guide</a> for more details about output data types. <ul> <li> `float`: Each returned embedding is a list of 32-bit (4-byte) <a href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" target="_blank">single-precision floating-point</a> numbers. This is the default and provides the highest precision / retrieval accuracy. </li> <li> `int8` and `uint8`: Each returned embedding is a list of 8-bit (1-byte) integers ranging from -128 to 127 and 0 to 255, respectively. </li> <li> `binary` and `ubinary`: Each returned embedding is a list of 8-bit integers that represent bit-packed, quantized single-bit embedding values: `int8` for `binary` and `uint8` for `ubinary`. The length of the returned list of integers is 1/8 of `output_dimension` (which is the actual dimension of the embedding). The `binary` type uses the offset binary method. Please refer to our guide for details on <a href="https://docs.voyageai.com/docs/flexible-dimensions-and-quantization#offset-binary" target="_blank">offset binary</a> and <a href="https://docs.voyageai.com/docs/flexible-dimensions-and-quantization#quantization" target="_blank">binary embeddings</a>. </ul>
  - `encoding_format` 'null' | 'base64', nullable — Format in which the embeddings are encoded. Defaults to `null`. Other options: `base64`. <ul> <li> If `null`, each embedding is an array of float numbers when `output_dtype` is set to `float` and as an array of integers for all other values of `output_dtype` (`int8`, `uint8`, `binary`, and `ubinary`). <li> If `base64`, the embeddings are represented as a <a href="https://docs.python.org/3/library/base64.html" target="_blank">Base64-encoded</a> NumPy array of: </li> <ul> <li> Floating-point numbers (<a href="https:/umpy.org/doc/2.1/user/basics.types.html#numerical-data-types" target="_blank">numpy.float32</a>) for <code>output_dtype</code> set to <code>float</code>. </li> <li> Signed integers (<a href="https:/umpy.org/doc/2.1/user/basics.types.html#numerical-data-types" target="_blank">numpy.int8</a>) for <code>output_dtype</code> set to <code>int8</code> or <code>binary</code>. </li> <li> Unsigned integers (<a href="https:/umpy.org/doc/2.1/user/basics.types.html#numerical-data-types" target="_blank">numpy.uint8</a>) for <code>output_dtype</code> set to <code>uint8</code> or <code>ubinary</code>. </li> </ul> </ul>

## Response `200`

Success

- EmbeddingsObject
  - `object` string — The object type, which is always `list`.
  - `data` object[] — An array of embedding objects.
    - `object` string — The object type, which is always `embedding`.
    - `embedding` number[] — Each embedding is a vector represented as an array of float numbers when `output_dtype` is set to `float` and as an array of integers for all other values of `output_dtype` (`int8`, `uint8`, `binary`, and `ubinary`). The length of this vector varies depending on the specific model, `output_dimension`, and `output_dtype`.
    - `index` integer — An integer representing the index of the embedding within the list of embeddings.
  - `model` string — Name of the model.
  - `usage` object
    - `total_tokens` integer — The total number of tokens used for computing the embeddings.

## Other responses

- `4XX` — Client error <p> This indicates an issue with the request format or frequency. Please see our [Error Codes](https://docs.voyageai.com/docs/error-codes) guide. </p>
- `5XX` — Server Error <p> 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. </p>

---

[API](https://skmtc.net/voyageai/apis/voyage-api.md) · [All operations](https://skmtc.net/voyageai/apis/voyage-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voyageai/voyage-api/revisions/b5a3e09c43ce/schema)