# Create contextualized chunk embeddings **POST /contextualizedembeddings** Creates contextualized vector embeddings for document chunks. These embeddings capture both local details within each chunk and global context from the entire document. This endpoint accepts queries, full documents, or document chunks and returns embeddings that are context-aware across the entire document. ## Servers - https://ai.mongodb.com/v1: https://ai.mongodb.com/v1 () ## Authentication methods - Api key auth ## Parameters ### Body: application/json (object) - **inputs** (array[array]) A list of lists, where each inner list contains a query, a document, or document chunks to be vectorized. Each inner list in `inputs` represents a set of text elements that are embedded together. Each element in the list is encoded not just independently, but also encodes context from the other elements in the same list. ``` inputs = [["text_1_1", "text_1_2", ..., "text_1_n"], ["text_2_1", "text_2_2", ..., "text_2_m"]] ``` **Document Chunks**. Most commonly, each inner list contains chunks from a single document, ordered by their position in the document. In this case: ``` inputs = [["doc_1_chunk_1", "doc_1_chunk_2", ..., "doc_1_chunk_n"], ["doc_2_chunk_1", "doc_2_chunk_2", ..., "doc_2_chunk_m"]] ``` Each chunk is encoded in context with the others from the same document, resulting in more context-aware embeddings. **Supplied chunks should not have any overlap.** **Context-Agnostic Behavior for Queries and Documents**. If there is one element per inner list, each text is embedded independently—similar to standard (context-agnostic) embeddings: ``` inputs = [["query_1"], ["query_2"], ..., ["query_k"]] inputs = [["doc_1"], ["doc_2"], ..., ["doc_k"]] ``` Therefore, if the inputs are queries, each inner list should contain a single query (a length of one), as shown above, and the `input_type` should be set to `query`. The following constraints apply to the `inputs` list: - The list must not contain more than 1,000 inputs. - The total number of tokens across all inputs must not exceed 120K. - The total number of chunks across all inputs must not exceed 16K. - **model** (string) The contextualized embedding model to use. Recommended model: `voyage-context-3`. - **input_type** (string | 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 or search purposes, where a "query" searches for relevant information among a collection of data referred to as "documents," specify whether your inputs are 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 or 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: "._ - **output_dimension** (integer | null) The number of dimensions for resulting output embeddings. Defaults to `null`. `voyage-context-3` supports the following `output_dimension` values: 2048, 1024 (default), 512, and 256. If set to `null`, the model uses the default value of 1024. - **output_dtype** (string) The data type for the embeddings to be returned. Defaults to `float`. Other options: `int8`, `uint8`, `binary`, `ubinary`. - `float`: Each returned embedding is a list of 32-bit (4-byte) [single-precision floating-point](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) 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. - **encoding_format** (string | 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 an array of integers for all other values of `output_dtype` (`int8`, `uint8`, `binary`, and `ubinary`). See `output_dtype` for more details. - If `base64`, the embeddings are represented as a [Base64-encoded](https://docs.python.org/3/library/base64.html) NumPy array of: - Floating-point numbers ([numpy.float32](https://numpy.org/doc/2.1/user/basics.types.html#numerical-data-types)) for `output_dtype` set to `float`. - Signed integers ([numpy.int8](https://numpy.org/doc/2.1/user/basics.types.html#numerical-data-types)) for `output_dtype` set to `int8` or `binary`. - Unsigned integers ([numpy.uint8](https://numpy.org/doc/2.1/user/basics.types.html#numerical-data-types)) for `output_dtype` set to `uint8` or `ubinary`. ## Responses ### 200 Success #### Body: application/json (object) - **object** (string) The object type, which is always "list". - **data** (array[object]) An array of contextualized embeddings. - **model** (string) Name of the model. - **usage** (object) ### 400 Invalid Request #### Body: application/json (object) - **detail** (string) The request is invalid. This error can occur due to invalid JSON, invalid parameter types, incorrect data types, batch size too large, total tokens exceeding the limit, or tokens in an example exceeding context length. ### 401 Unauthorized #### Body: application/json (object) - **detail** (string) Invalid authentication. Ensure your model API key is correctly specified in the Authorization header as `Bearer YOUR_API_KEY`. ### 403 Forbidden #### Body: application/json (object) - **detail** (string) Access forbidden. This may occur if the IP address you are sending the request from is not allowed. ### 429 Rate Limit Exceeded #### Body: application/json (object) - **detail** (string) Rate limit exceeded. Your request frequency or token usage is too high. Reduce your request rate or wait before retrying. ### 500 Internal Server Error #### Body: application/json (object) - **detail** (string) An unexpected error occurred on the server. Retry your request after a brief wait. ### 502 Bad Gateway #### Body: application/json (object) - **detail** (string) The server received an invalid response from an upstream server. Retry your request after a brief wait. ### 503 Service Unavailable #### Body: application/json (object) - **detail** (string) The service is temporarily unavailable due to high traffic or maintenance. Retry your request after a brief wait. ### 504 Gateway Timeout #### Body: application/json (object) - **detail** (string) The server did not receive a timely response from an upstream server. Retry your request after a brief wait. [Powered by Bump.sh](https://bump.sh)