Text embedding models

post

https://api.voyageai.com/v1/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.

Body Params

input

required

A single text string, or a list of texts as a list of strings, such as ["I like cats", "I also like dogs"]. Currently, we have two constraints on the list:

The maximum length of the list is 1,000.
The total number of tokens in the list is at most 1M for voyage-4-lite and voyage-3.5-lite; 320K for voyage-4, voyage-3.5 and voyage-2; and 120K for voyage-4-large, voyage-3-large, voyage-code-3, voyage-finance-2, and voyage-law-2.

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

string | null

enum

Defaults to null

Type of the input text. Defaults to null. Other options: query, document.

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.
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 document for retrieval: ".

Allowed:

truncation

boolean

Defaults to true

Whether to truncate the input texts to fit within the context length. Defaults to true.

If true, an 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.

output_dimension

integer | null

Defaults to null

The number of dimensions for resulting output embeddings. Defaults to null.

Most models only support a single default dimension, used when output_dimension is set to null (see output embedding dimensions here).
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.

output_dtype

string

enum

Defaults to float

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 guide for more details about output data types.

float: Each returned embedding is a list of 32-bit (4-byte) single-precision floating-point numbers. This is the default and provides the highest precision / retrieval accuracy.
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.
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 offset binary and binary embeddings.

Allowed:

encoding_format

string | null

enum

Defaults to null

Format in which the embeddings are encoded. Defaults to null. Other options: base64.

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).
If base64, the embeddings are represented as a Base64-encoded NumPy array of:

Floating-point numbers (numpy.float32) for output_dtype set to float.
Signed integers (numpy.int8) for output_dtype set to int8 or binary.
Unsigned integers (numpy.uint8) for output_dtype set to uint8 or ubinary.

Allowed:

Responses

5XX

Server Error

This indicates our servers are experiencing high traffic or having an unexpected issue. Please see our Error Codes guide.

200Success

4XXClient error This indicates an issue with the request format or frequency. Please see our Error Codes guide.