Skip to main content

Voyage AI Provider Guide

Top-tier RAG embeddings — text-only provider exposing embed() and embedMany() (chat / streaming intentionally not supported)

Overview​

Voyage AI provides some of the highest-accuracy text embeddings available today, particularly strong on retrieval and reranking benchmarks. NeuroLink wraps api.voyageai.com/v1/embeddings so the same embed() / embedMany() contract used by every other embedding-capable provider works for Voyage.

  • voyage-3.5 — latest general-purpose (default)
  • voyage-3-large — flagship; highest accuracy
  • voyage-3.5-lite — smaller / cheaper
  • voyage-code-3 — code-tuned (best for code retrieval)
  • voyage-finance-2, voyage-law-2 — domain-tuned
  • voyage-multilingual-2 — non-English / cross-lingual

Key Facts​

  • Protocol: Native REST API (/embeddings only — not OpenAI-compat for chat)
  • Default base URL: https://api.voyageai.com/v1
  • Default model: voyage-3.5
  • Max input tokens: 32K (16K on voyage-law-2)
  • Streaming / chat / tool calling: NOT supported (embedding-only; executeStream and getAISDKModel throw a friendly error)
  • Pricing: Per-million input tokens; output dimension is the embedding vector, not generated tokens

Quick Start​

1. Get an API Key​

Sign up at https://www.voyageai.com/ and create an API key at https://dash.voyageai.com/api-keys.

2. Configure Environment​

# Required
VOYAGE_API_KEY=pa-...

# Optional: override the default model (default: voyage-3.5)
VOYAGE_MODEL=voyage-3-large

# Optional: override the base URL
# VOYAGE_BASE_URL=https://api.voyageai.com/v1

3. Generate Your First Embedding​

import { NeuroLink } from "@juspay/neurolink";

const ai = new NeuroLink();

const vector = await ai.embed("The quick brown fox jumps over the lazy dog", {
  provider: "voyage",
});

console.log(`Vector length: ${vector.length}`); // 1024 for voyage-3.5

SDK Usage​

Single Embedding​

const vector = await ai.embed("Why is the sky blue?", {
  provider: "voyage",
  model: "voyage-3.5",
});
// vector: number[]

Batch Embeddings​

const vectors = await ai.embedMany(
  ["Document 1 content...", "Document 2 content...", "Document 3 content..."],
  { provider: "voyage", model: "voyage-3-large" },
);
// vectors: number[][]

Code Embeddings​

const codeVector = await ai.embed(
  `function fibonacci(n) { return n < 2 ? n : fibonacci(n-1) + fibonacci(n-2); }`,
  { provider: "voyage", model: "voyage-code-3" },
);

Per-Call Credentials​

const vector = await ai.embed("text", {
  provider: "voyage",
  credentials: { voyage: { apiKey: "user-specific-key" } },
});

Voyage embeddings plug into NeuroLink's RAG pipeline. Configure the RAG embedder to use Voyage:

const result = await ai.generate({
  provider: "openai", // any chat-capable provider for the LLM half
  prompt: "What are the key features?",
  rag: {
    files: ["./docs/guide.md"],
    embedder: { provider: "voyage", model: "voyage-3.5" },
  },
});

CLI Usage​

Voyage is embedding-only — there is no cli generate flow because generate is a chat-completion path. Use the SDK directly, or use Voyage as the embedder behind a RAG-enabled cli generate:

pnpm run cli generate "What does the README say?" \
  --provider openai \
  --rag-files ./README.md \
  --rag-embedder voyage:voyage-3.5

Provider Aliases​

AliasExample
voyage--provider voyage
voyage-ai--provider voyage-ai

(Note: aliases are mostly relevant for RAG embedder routing; standalone chat use is not supported.)

Configuration Reference​

Environment VariableRequiredDefaultDescription
VOYAGE_API_KEYYes—Voyage AI API key
VOYAGE_MODELNovoyage-3.5Default embedding model
VOYAGE_BASE_URLNohttps://api.voyageai.com/v1Base URL

Model Reference​

Per the Voyage embeddings docs:

ModelDefault dimTokensBest For
voyage-3.5102432KGeneral-purpose (default)
voyage-3.5-lite102432KSmaller / cheaper
voyage-3-large102432KFlagship; highest accuracy
voyage-code-3102432KCode retrieval
voyage-finance-2102432KFinance domain
voyage-law-2102416KLegal domain
voyage-multilingual-2unspecified32KCross-lingual

Matryoshka flexible dimensions: voyage-3.5, voyage-3.5-lite, voyage-3-large, and voyage-code-3 all support flexible output dimensions of 256 / 512 / 1024 / 2048 via the output_dimension parameter on the Voyage API. The default (and what NeuroLink currently returns) is 1024. voyage-finance-2, voyage-law-2, and voyage-multilingual-2 only emit the default dimension. See the FAQ below for how to request a smaller dimension explicitly.

Feature Support Matrix​

Featurevoyage-3.5voyage-3-largevoyage-code-3
EmbeddingsYesYesYes
Single embedYesYesYes
Batch embedYes (128 inputs/req)YesYes
Text generationNoNoNo
StreamingNoNoNo
Tool callingNoNoNo
VisionNoNoNo

Troubleshooting​

"Invalid Voyage AI API key"​

echo $VOYAGE_API_KEY
export VOYAGE_API_KEY=pa-...

Get / rotate at https://dash.voyageai.com/api-keys.

"Voyage AI rate limit exceeded"​

Voyage has per-minute and daily limits per tier. Free-tier is generous for development; production usage typically requires the paid tier. Implement exponential backoff or use embedMany (batched) instead of many single embed calls.

"embed() / embedMany() not available"​

Voyage IS embedding-only — these methods work. If you see "not supported" errors, verify you're using provider: "voyage" and the API key is set. For chat / streaming on Voyage, you can't — pick a different provider (xAI / Groq / OpenAI / etc.).

"voyage-3.5 returns 1024-dim, but I want 512"​

Use voyage-3.5-lite (native 512-dim) instead. Voyage doesn't currently expose a dimensions parameter on the standard models — pick the right model for the dimension you need.

"How do I rerank with Voyage?"​

Voyage doesn't expose rerank through this provider class today. For reranking, use the Jina AI provider (see src/lib/providers/jina.ts) which exposes rerank() directly.

See Also​

  • Jina AI — sibling embedding-only provider with reranking support (no setup doc yet; see src/lib/providers/jina.ts)
  • RAG Integration — how to use Voyage embeddings in the RAG pipeline
  • Adding a new LLM provider — covers the embedding-only override pattern in §H

Need Help? Open a GitHub Discussion or issue.