--- title: Voyage AI description: Learn how to use Voyage AI with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/voyage" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). The [Voyage AI](https://www.voyageai.com/) provider contains embedding and reranking model support for the Voyage AI API. You can use Voyage AI models through [AI Gateway](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/voyage`. ```ts provider="voyage" model="voyage/voyage-4" import { embed } from 'ai'; const { embedding } = await embed({ model: "voyage/voyage-4", value: 'A vegetarian lasagna recipe.', }); console.log(embedding); ``` ## Using AI Gateway The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options). ## Using `@ai-sdk/voyage` For direct access to Voyage AI, install `ai` and `@ai-sdk/voyage`: ```bash pnpm add ai @ai-sdk/voyage ``` Set your Voyage AI API credential in the `VOYAGE_API_KEY` environment variable: ```bash export VOYAGE_API_KEY=your_api_key_here ``` AI Gateway does not expose every API in `@ai-sdk/voyage`. Use the direct provider for provider-specific APIs or custom connection settings. The following sections document the direct `@ai-sdk/voyage` provider, including its model factories and settings. Gateway model and feature availability can differ. ## Provider Instance You can import the default provider instance `voyage` from `@ai-sdk/voyage`: ```ts import { voyage } from '@ai-sdk/voyage'; ``` If you need a customized setup, you can import `createVoyage` from `@ai-sdk/voyage` and create a provider instance with your settings: ```ts import { createVoyage } from '@ai-sdk/voyage'; const voyage = createVoyage({ // custom settings }); ``` You can use the following optional settings to customize the Voyage AI provider instance: - **baseURL** *string* Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is `https://api.voyageai.com/v1`. - **apiKey** *string | PromiseLike\ | (() => string | PromiseLike\)* Pass a function to resolve credentials before each request, including when keys rotate. The function can return a string or a promise. Credential caching and refresh are managed by the function. API key that is being sent using the `Authorization` header. It defaults to the `VOYAGE_API_KEY` environment variable. - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation. Defaults to the global `fetch` function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing. ## Embedding Models You can create models that call the [Voyage AI embeddings API](https://docs.voyageai.com/reference/embeddings-api) using the `.embedding()` factory method. ```ts const model = voyage.embedding('voyage-4'); ``` You can use Voyage AI embedding models to generate embeddings with the `embed` function: ```ts import { voyage } from '@ai-sdk/voyage'; import { embed } from 'ai'; const { embedding } = await embed({ model: voyage.embedding('voyage-4'), value: 'sunny day at the beach', }); ``` Voyage AI embedding models support additional provider options that can be passed via `providerOptions.voyage`: ```ts import { voyage, type VoyageEmbeddingModelOptions } from '@ai-sdk/voyage'; import { embed } from 'ai'; const { embedding } = await embed({ model: voyage.embedding('voyage-4-large'), value: 'sunny day at the beach', providerOptions: { voyage: { inputType: 'document', outputDimension: 512, } satisfies VoyageEmbeddingModelOptions, }, }); ``` The following provider options are available: - **inputType** *'query' | 'document' | null* Specifies the type of input passed to the model. Defaults to `null`. - `null`: The embedding model directly converts the inputs into numerical vectors. - `'query'`: Used for embeddings of search queries run against a vector DB to find relevant documents. - `'document'`: Used for embeddings stored in a vector database for search use-cases. - **truncation** *boolean* Whether to truncate the input texts to fit within the model's context length. Defaults to `true`. - **outputDimension** *number* The number of dimensions for the resulting output embeddings. Supported by models with flexible dimensions (e.g. `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-4-nano`, `voyage-code-3.5`, `voyage-code-3`, `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`). Supported values: 256, 512, 1024, 2048. - **outputDtype** *'float' | 'int8' | 'uint8' | 'binary' | 'ubinary'* The data type for the output embeddings. Defaults to `'float'`. - `'float'`: 32-bit floating-point numbers. - `'int8'`, `'uint8'`: 8-bit integer types. - `'binary'`, `'ubinary'`: Bit-packed, quantized single-bit embedding values. ### Model Capabilities | Model | Default Dimensions | Context Length | Custom Dimensions | Max Values per Call | | ----------------- | ------------------ | -------------- | ----------------- | ------------------- | | `voyage-4-large` | 1024 | 32,000 | ✓ | 128 | | `voyage-4` | 1024 | 32,000 | ✓ | 128 | | `voyage-4-lite` | 1024 | 32,000 | ✓ | 128 | | `voyage-4-nano` | 1024 | 32,000 | ✓ | 128 | | `voyage-code-3.5` | 1024 | 32,000 | ✓ | 128 | | `voyage-code-3` | 1024 | 32,000 | ✓ | 128 | | `voyage-3-large` | 1024 | 32,000 | ✓ | 128 | | `voyage-3.5` | 1024 | 32,000 | ✓ | 128 | | `voyage-3.5-lite` | 1024 | 32,000 | ✓ | 128 | The table above lists popular models. Please see the [Voyage AI docs](https://docs.voyageai.com/docs/embeddings) for a full list of available models. You can also pass any available provider model ID as a string if needed. ## Reranking Models You can create models that call the [Voyage AI rerank API](https://docs.voyageai.com/reference/rerank-api) using the `.reranking()` factory method. ```ts const model = voyage.reranking('rerank-2.5'); ``` You can use Voyage AI reranking models to rerank documents with the `rerank` function: ```ts import { voyage } from '@ai-sdk/voyage'; import { rerank } from 'ai'; const documents = [ 'sunny day at the beach', 'rainy afternoon in the city', 'snowy night in the mountains', ]; const { ranking } = await rerank({ model: voyage.reranking('rerank-2.5'), documents, query: 'talk about rain', topN: 2, }); console.log(ranking); ``` Voyage AI reranking models support additional provider options that can be passed via `providerOptions.voyage`: ```ts import { voyage, type VoyageRerankingModelOptions } from '@ai-sdk/voyage'; import { rerank } from 'ai'; const { ranking } = await rerank({ model: voyage.reranking('rerank-2.5'), documents: ['sunny day at the beach', 'rainy afternoon in the city'], query: 'talk about rain', providerOptions: { voyage: { returnDocuments: true, truncation: true, } satisfies VoyageRerankingModelOptions, }, }); ``` The following provider options are available: - **returnDocuments** *boolean* Whether to return the documents in the response. Defaults to `false`. - **truncation** *boolean* Whether to truncate the input texts to fit within the model's context length. Defaults to `true`. ### Model Capabilities | Model | Context Length | Text Documents | Object Documents | Top N | | ----------------- | -------------- | -------------- | ---------------- | ----- | | `rerank-2.5` | 32,000 | ✓ | ✓ | ✓ | | `rerank-2.5-lite` | 32,000 | ✓ | ✓ | ✓ | | `rerank-2` | 16,000 | ✓ | ✓ | ✓ | | `rerank-2-lite` | 8,000 | ✓ | ✓ | ✓ | | `rerank-1` | 8,000 | ✓ | ✓ | ✓ | | `rerank-lite-1` | 4,000 | ✓ | ✓ | ✓ | ## Provider Option Reference The following option definitions are generated from the provider catalog. | Operation | Option | Description | | --------- | ----------------- | --------------- | | embedding | `inputType` | inputType | | embedding | `truncation` | truncation | | embedding | `outputDimension` | outputDimension | | embedding | `outputDtype` | outputDtype | | reranking | `returnDocuments` | returnDocuments | | reranking | `truncation` | truncation | --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)