> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Contextualized Chunk Embeddings

`voyage-context-4` is a contextualized chunk embedding model that produces vectors for chunks that capture the full document context without any manual metadata and context augmentation. This leads to higher retrieval accuracies than with or without augmentation. The model is also simpler, faster, and cheaper. It serves as a drop-in replacement for standard embeddings without downstream workflow changes and reduces chunking strategy sensitivity.

To learn more, see the [blog post.](https://blog.voyageai.com/2026/06/29/voyage-context-4/)

## Available Models

| Model | Context Length | Dimensions | Description |
| --- | --- | --- | --- |
| `voyage-context-4` | 120,000 tokens * | 1024 (default), 256, 512, 2048 | Contextualized chunk embeddings optimized for general-purpose and multilingual retrieval quality. |

**Note:**

\* The total number of tokens across all inputs must not exceed 120K if `enable_auto_chunk = true`; otherwise they must not exceed 32K.

### Older Contextualized Chunk Embedding Models

#### The following older models are still accessible from the API, but we recommend using the new models for better quality and efficiency.

The latest models perform better than the legacy models in all aspects, such as quality, context length, latency, and throughput.

| Model | Context Length | Dimensions | Description |
| --- | --- | --- | --- |
| `voyage-context-3` | 120,000 tokens * | 1024 (default), 256, 512, 2048 | Contextualized chunk embeddings optimized for general-purpose and multilingual retrieval quality. To learn more, see the [blog post.](https://www.mongodb.com/company/blog/product-release-announcements/voyage-context-3-focused-chunk-level-details-global-document-context) |

## Tutorial

For a tutorial on using contextualized chunk embeddings, see [Semantic Search with Voyage AI Embeddings.](https://www.mongodb.com/docs/voyageai/tutorials/semantic-search.md#std-label-voyage-semantic-search)

## Usage

You can access Voyage contextualized chunk embeddings in Python through the `voyageai` package. Install the `voyageai` package, set up the API key, and use the `voyageai.Client.contextualized_embed()` function to vectorize your inputs.

```python
voyageai.Client.contextualized_embed(
    inputs: Union[List[List[str]], List[str]], # see below for specifics on when to pass one or the other.
    model: str,
    input_type: Optional[str] = None,
    output_dimension: Optional[int] = None,
    output_dtype: Optional[str] = "float",
    enable_auto_chunking: Optional[bool] = False,
    chunk_size: Optional[int] = 512,
    chunk_overlap: Optional[int] = 0,
    chunk_fn: Optional[Callable[[str], List[str]]] = None,
)
```

### Parameters

#### View the parameters for the contextualized\_embed method.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `inputs` | `List[List[str]]` or `List[str]` | Yes | The input texts to be vectorized. |
| `model` | String | Yes | Name of the model. Recommended option: `voyage-context-4`. |
| `input_type` | String | No | Type of the input text. Options: `None`, `query`, `document`. When `input_type` is `None`, the model directly converts the inputs into numerical vectors. For retrieval and search, we recommend setting `input_type` to `query` or `document`. In those cases, Voyage automatically prepends a prompt before vectorizing the input. Embeddings generated with and without `input_type` are compatible. |
| `output_dimension` | Integer | No | The number of dimensions for resulting embeddings. Options: 2048, 1024 (default), 512, and 256. |
| `output_dtype` | String | No | The data type for returned embeddings. Options: `float`, `int8`, `uint8`, `binary`, `ubinary`. See [Flexible Dimensions and Quantization](https://www.mongodb.com/docs/voyageai/tutorials/dimensions-and-quantization.md#std-label-voyage-flexible-dims-quantization) for details. **float**: Each embedding is a list of 32-bit floating-point numbers.; **int8** and **uint8**: Each embedding is a list of 8-bit integers.; **binary** and **ubinary**: Each embedding is a list of 8-bit integers representing bit-packed single-bit values. The returned list length is 1/8 of `output_dimension`. `binary` uses offset binary. |
| `enable_auto_chunking` | Boolean | No | Whether to automatically chunk each input document on the backend. Defaults to `False`. When `True`, `inputs` must be a flat `List[str]` of full-document strings, and `input_type` must be `document`. |
| `chunk_size` | Integer | No | Target chunk size in tokens when `enable_auto_chunking=True`. If omitted, the server resolves it to 512. `chunk_size` must not exceed 32K. |
| `chunk_overlap` | Integer | No | Chunk overlap in tokens when `enable_auto_chunking=True`. Defaults to `0`. `chunk_overlap` must be smaller than `chunk_size`. Only a valid input when `enable_auto_chunking=True`. |
| `chunk_fn` | Function (`Callable[[str], List[str]]`) | No | A custom client-side chunking function. Defaults to `None`. If provided, it is applied locally to each input string before the request is sent. For convenience, `voyageai.default_chunk_fn` is available. Use `chunk_fn` for client-side chunking only; it cannot be combined with `enable_auto_chunking=True`. |

**Note:**

- The listed limits for both `chunk_size` and `chunk_overlap` are upper bounds. The actual `chunk_size` and `chunk_overlap` can be less than the value passed, but cannot be higher.

- Overlapping tokens are billed in the same way as input tokens.

### Response

#### View the response for the contextualized\_embed method.

This method returns a `ContextualizedEmbeddingsObject`, which contains the following attributes:

A `ContextualizedEmbeddingsObject`, containing the following attributes:

| Attribute | Type | Description |
| --- | --- | --- |
| `results` | `List[ContextualizedEmbeddingsResult]` | One result per query or document. Each `ContextualizedEmbeddingsResult` contains the following attributes: `embeddings` (`List[List[float]]` or `List[List[int]]`): Embeddings corresponding to a query, a document, or chunks from the same document. For document chunks, embeddings are ordered to match chunk order.; `chunk_texts` (`List[str]`): Chunk text returned by the Python SDK for chunked document results. If you provide a client-side `chunk_fn`, these correspond to the chunks produced by that function. When auto-chunking is enabled, they correspond to the backend-generated chunks.; `index` (`int`): The index of the query or document in the input list. |
| `total_tokens` | Integer | The total number of tokens in the input texts. |

Example: see the [quickstart.](https://www.mongodb.com/docs/voyageai/quickstart.md#std-label-voyage-quickstart)

### Quick Reference: Valid Parameter Combinations

| Use Case | `inputs` Shape | `input_type` | `enable_auto_chunking` | `chunk_fn` | Notes |
| --- | --- | --- | --- | --- | --- |
| Embed pre-chunked documents | `List[List[str]]` | `document` | `False` or omitted | Omitted | Each inner list contains one document's chunks |
| Client-side chunking and embedding | `List[List[str]]` | `document` | `False` or omitted | Provided | Common pattern: one full document string per inner list |
| Auto chunking and embedding | `List[str]` | `document` | `True` | Omitted | `chunk_size` and `chunk_overlap` apply only in this mode |
| Embed queries | `List[str]` or `List[List[str]]` | `query` | `False` or omitted | Omitted | If nested, each inner list should contain a single query |

### Quickstart

**Auto Chunking and Embedding**

Use this when you want Voyage to split each full document into chunks for you.

```python
import voyageai

vo = voyageai.Client()

documents = [
    "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.\nThe company's revenue increased by 15% compared to the previous quarter.",
    "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.\nThe company's revenue decreased by 2% compared to the previous quarter.",
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=documents,
    input_type="document",
    enable_auto_chunking=True,
    chunk_size=512,
    chunk_overlap=0,
)
```

When auto-chunking is enabled, the backend splits each full document into chunks before embedding.

**Embed Pre-Chunked Documents**

Use this when you have already split each document into chunks on the client side.

```python
import voyageai

vo = voyageai.Client()

inputs = [
    [
        "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.",
        "The company's revenue increased by 15% compared to the previous quarter.",
    ],
    [
        "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.",
        "The company's revenue decreased by 2% compared to the previous quarter.",
    ],
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=inputs,
    input_type="document",
)
```

Each inner list is embedded as a group, so each chunk is encoded in the context of the other chunks from the same document.

**Client-Side Chunking and Embedding**

Use this when you have full documents and want to handle chunking locally in the Python SDK rather than in the backend.

```python
import voyageai

vo = voyageai.Client()

inputs = [
    [
        "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.\nThe company's revenue increased by 15% compared to the previous quarter.",
    ],
    [
        "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.\nThe company's revenue decreased by 2% compared to the previous quarter.",
    ],
]

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=inputs,
    input_type="document",
    chunk_fn=voyageai.default_chunk_fn,
)
```

`chunk_fn` is applied locally to each input string before the request is sent.

**Embedding Queries**

Use this when your inputs are search queries.

```python
import voyageai

vo = voyageai.Client()

result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=[
        "What was the revenue growth for Leafy Inc. in Q2 2024?",
        "What changed in Greenery Corp. between Q1 and Q2 2024?",
    ],
    input_type="query",
)
```

The following query input shape is also valid and is treated equivalently:

```python
result = vo.contextualized_embed(
    model="voyage-context-4",
    inputs=[
        ["What was the revenue growth for Leafy Inc. in Q2 2024?"],
        ["What changed in Greenery Corp. between Q1 and Q2 2024?"],
    ],
    input_type="query",
)
```

### Returned Chunk Text

The response contains contextualized embedding results for each query or document. For document chunks, embeddings are ordered to match chunk order.

In the Python SDK, returned chunk text is available through `chunk_texts` on the result object. In the REST API, returned chunk text is available as `text` on each embedding item.

If you provide a client-side chunking function, the returned chunk text corresponds to the chunks produced by that function. When auto-chunking is enabled, the response also includes the backend-generated chunk text for each returned embedding so you can inspect and store it.

You can access Voyage contextualized chunk embeddings in TypeScript through the `voyageai` package. Install the `voyageai` package, set up the API key, and use the `VoyageAIClient.contextualizedEmbed()` method to vectorize your inputs.

The TypeScript client sends requests to the Voyage platform endpoint (`https://api.voyageai.com/v1`) by default. To use a [model API key](https://www.mongodb.com/docs/voyageai/management/api-keys.md#std-label-voyage-api-keys), set the `environment` option to `https://ai.mongodb.com/v1` when you create the client, as shown in the following example. To learn more about the client, see [TypeScript Client.](https://www.mongodb.com/docs/voyageai/api-and-clients.md#std-label-voyage-typescript-client)

### Example

The following example embeds two pre-chunked documents. Each inner array contains one document's chunks, so each chunk is encoded in the context of the other chunks from the same document.

```typescript
import { VoyageAIClient } from "voyageai";

// To use a model API key created in the Atlas UI, set the
// environment option to https://ai.mongodb.com/v1
const client = new VoyageAIClient({
  apiKey: process.env.VOYAGE_API_KEY,
  environment: "https://ai.mongodb.com/v1",
});

// Each inner array contains the chunks of one document
const inputs = [
  [
    "This is the SEC filing on Leafy Inc.'s Q2 2024 performance.",
    "The company's revenue increased by 15% compared to the previous quarter.",
  ],
  [
    "This is the SEC filing on Elephant Ltd.'s Q2 2024 performance.",
    "The company's revenue decreased by 2% compared to the previous quarter.",
  ],
];

const result = await client.contextualizedEmbed({
  inputs: inputs,
  model: "voyage-context-4",
  inputType: "document",
});

console.log(`Embedding dimension: ${result.results[0].embeddings[0].length}`);
console.log(`Total tokens used: ${result.totalTokens}`);

```

The `contextualizedEmbed()` method returns a result object whose `results` field contains one item per input document. Each item's `embeddings` field contains one embedding per chunk, ordered to match chunk order. The `totalTokens` field contains the total number of tokens processed.

You can access Voyage contextualized chunk embeddings in Java by sending HTTP requests using the built-in `HttpClient` or other HTTP libraries.

### Example

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String apiKey = System.getenv("VOYAGE_API_KEY");
String url = "https://api.voyageai.com/v1/contextualizedembeddings";

String jsonBody = """
    {
        "inputs": [
            ["doc_1_chunk_1", "doc_1_chunk_2"],
            ["doc_2_chunk_1", "doc_2_chunk_2"]
        ],
        "input_type": "document",
        "model": "voyage-context-4"
    }
    """;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Authorization", "Bearer " + apiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

You can access Voyage contextualized chunk embeddings in Go by sending HTTP requests using the standard `net/http` package.

### Example

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("VOYAGE_API_KEY")
    url := "https://api.voyageai.com/v1/contextualizedembeddings"

    // Example input containing chunks from two documents
    inputs := [][]string{
        {"doc_1_chunk_1", "doc_1_chunk_2"},
        {"doc_2_chunk_1", "doc_2_chunk_2"},
    }

    requestBody := map[string]interface{}{
        "inputs":     inputs,
        "input_type": "document",
        "model":      "voyage-context-4",
    }

    jsonData, _ := json.Marshal(requestBody)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

### REST API

Voyage contextualized chunk embeddings are available at:

`POST https://api.voyageai.com/v1/contextualizedembeddings`

See the Contextualized Embeddings API reference.

### Response Shape

The REST API returns chunk text as `text` on each individual embedding item, not as a top-level `chunk_texts` list.

```json
{
  "data": [
    {
      "data": [
        { "embedding": ["..."], "index": 0, "text": "chunk text here" },
        { "embedding": ["..."], "index": 1, "text": "..." }
      ],
      "index": 0
    }
  ],
  "model": "voyage-context-4",
  "usage": { "total_tokens": 100 },
  "chunker_version": "1.0.0"
}
```

- `data` - A list of results, one per input query or document.

- `data[].data` - A list of embedding items for that input.

- `data[].data[].embedding` - The embedding vector.

- `data[].data[].index` - The chunk index within that input.

- `data[].data[].text` - The returned chunk text for that embedding item.

- `model` - The model used.

- `usage.total_tokens` - Total tokens processed.

- `chunker_version` - The version of the server-side chunker. This is returned when auto-chunking is enabled.

### Example

```bash
curl -X POST https://api.voyageai.com/v1/contextualizedembeddings \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "inputs": [
      "This is the SEC filing on Leafy Inc.'\''s Q2 2024 performance.\nThe company'\''s revenue increased by 15% compared to the previous quarter.",
      "This is the SEC filing on Elephant Ltd.'\''s Q2 2024 performance.\nThe company'\''s revenue decreased by 2% compared to the previous quarter."
    ],
    "input_type": "document",
    "model": "voyage-context-4",
    "enable_auto_chunking": true,
    "chunk_size": 512,
    "chunk_overlap": 0
  }'
```