Voyage AI

The Voyage AI provider contains embedding and reranking model support for the Voyage AI API. You can use Voyage AI models through AI Gateway (recommended) or connect directly with @ai-sdk/voyage.

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:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

Gateway feature and provider-option support depends on the model and the provider serving the request. See Gateway provider options.

Using @ai-sdk/voyage

For direct access to Voyage AI, install ai and @ai-sdk/voyage:

pnpm add ai @ai-sdk/voyage

npm install ai @ai-sdk/voyage

yarn add ai @ai-sdk/voyage

bun add ai @ai-sdk/voyage

Set your Voyage AI API credential in the VOYAGE_API_KEY environment variable:

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.

Provider Instance

You can import the default provider instance voyage from @ai-sdk/voyage:

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:

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

  API key that is being sent using the Authorization header. It defaults to the VOYAGE_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom 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 using the .embedding() factory method.

const model = voyage.embedding('voyage-4');

You can use Voyage AI embedding models to generate embeddings with the embed function:

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:

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

Reranking Models

You can create models that call the Voyage AI rerank API using the .reranking() factory method.

const model = voyage.reranking('rerank-2.5');

You can use Voyage AI reranking models to rerank documents with the rerank function:

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:

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