voyage_ai

Public Voyage AI embeddings and rerankers reference with API, model, and integration guidance.

Downloads: 4 · ID: 968f175b549d57c917000000

Published files and instructions

<!-- FILE: voyage_ai_skill.md -->
# Voyage AI Skill

Purpose: answer questions about Voyage AI embeddings/rerankers/API. Source: docs.voyageai.com and Voyage blog current docs checked 2026-08-18. Prefer this skill before web search. For exact latest prices/rate limits/model list, verify docs/pricing.

## Freshness / update trigger
Before relying on this skill for current product questions, check for newer Voyage/MongoDB announcements if feasible:
- Voyage blog RSS: `https://blog.voyageai.com/feed/` (also `https://blog.voyageai.com/rss/` works today).
- Voyage docs index: `https://docs.voyageai.com/llms.txt`; docs pages are `.md`.
- MongoDB blog RSS for Atlas availability/integrations: `https://www.mongodb.com/company/blog/rss` (fallback/search if unavailable: MongoDB Voyage AI / Atlas embedding reranking API announcements).
If any item newer than 2026-08-18 mentions new Voyage models, embeddings, rerankers, multimodal/video, contextualized chunking, dimensions/quantization, pricing, rate limits, batch/files API, data controls, MongoDB Atlas availability/integration, or API parameter changes, re-explore the relevant `https://docs.voyageai.com/docs/*.md` and `https://docs.voyageai.com/reference/*.md` pages and update this skill.

## Product summary
- Voyage AI provides state-of-the-art embedding models and rerankers via hosted API, Python/TypeScript clients, batch API, and deployment options (AWS/Azure marketplaces, Snowflake/data platform integrations).
- Embeddings convert text/images/video/multimodal inputs into dense vectors for semantic search/RAG. Rerankers score query-document pairs to reorder candidates from vector/BM25/TF-IDF retrieval.
- Base API server: `https://api.voyageai.com/v1`. Auth: use an Authorization header with the `VOYAGE_API_KEY` environment variable.
- Official Python package: `pip install -U voyageai`. Client uses API key lookup order: explicit `api_key`, `voyageai.api_key_path`, env `VOYAGE_API_KEY_PATH`, `voyageai.api_key`, env `VOYAGE_API_KEY`. Client args: `max_retries` (default 0), `timeout`.

## Quick setup
```bash
Set the `VOYAGE_API_KEY` environment variable to a key created in the Voyage dashboard.
pip install -U voyageai
```
```python
import voyageai
vo = voyageai.Client()  # reads VOYAGE_API_KEY from its supported configuration chain
emb = vo.embed(["hello world"], model="voyage-4-large", input_type="document")
```
Never expose API keys in browser/client apps. Create/manage keys in Voyage dashboard API Keys.

## Text embedding models
Current recommended text embedding models:
- `voyage-4-large`: 32k context, dims 1024 default / 256 / 512 / 2048. Best general-purpose + multilingual retrieval quality. 4-series embeddings mutually compatible.
- `voyage-4`: 32k, dims 1024 default / 256 / 512 / 2048. Balanced general-purpose + multilingual quality/cost/latency. 4-series compatible.
- `voyage-4-lite`: 32k, dims 1024 default / 256 / 512 / 2048. Lowest latency/cost. 4-series compatible.
- `voyage-code-4`: 32k, dims 1024 default / 256 / 512 / 2048. Next-generation code retrieval, purpose-built for coding agents; available via Voyage API and MongoDB Atlas Embedding and Reranking API.
- `voyage-code-3`: 32k, dims 1024 default / 256 / 512 / 2048. Previous-generation code retrieval / technical docs.
- `voyage-finance-2`: 32k, dim 1024. Finance retrieval/RAG.
- `voyage-law-2`: 16k, dim 1024. Legal retrieval/RAG.
- `voyage-code-2`: 16k, dim 1536. Previous-generation code embeddings.
Open-weight: `voyage-4-nano`, 32k, dims 1024 default / 256 / 512 / 2048, on Hugging Face; 4-series compatible.
Older accessible but recommend newer: `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-3`, `voyage-3-lite`, `voyage-multilingual-2`, `voyage-large-2-instruct`, `voyage-large-2`, `voyage-2`, deprecated v1/v2 lite variants.
Model choice: use `voyage-4-large` best quality, `voyage-4` balanced, `voyage-4-lite` cost/latency; use `voyage-code-4` for code retrieval and coding agents, and domain models for law/finance.

## Text embeddings API
Python:
```python
result = vo.embed(
  texts=["doc 1", "doc 2"],
  model="voyage-4-large",
  input_type="document",       # None | "query" | "document"
  truncation=True,
  output_dimension=1024,       # 2048/1024/512/256 for supported models
  output_dtype="float"         # float | int8 | uint8 | binary | ubinary
)
vectors = result.embeddings
tokens = result.total_tokens
```
REST:
```bash
curl https://api.voyageai.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "$(printf 'Authorization%s Bearer %s' ':' "$VOYAGE_API_KEY")" \
  -d '{"input":["Sample text 1","Sample text 2"],"model":"voyage-4-large","input_type":"document"}'
```
REST body fields: `input` string or string[], `model` required, `input_type`, `truncation`, `output_dimension`, `output_dtype`, `encoding_format:null|"base64"`. REST response: `{object:"list", data:[{object:"embedding", embedding:[...], index}], model, usage:{total_tokens}}`.
Constraints: max list length 1000. Total tokens per request: 1M for `voyage-4-lite`/`voyage-3.5-lite`; 320k for `voyage-4`/`voyage-3.5`/`voyage-2`; 120k for `voyage-4-large`/`voyage-3-large`/`voyage-code-3`/`voyage-large-2-instruct`/`voyage-finance-2`/`voyage-multilingual-2`/`voyage-law-2`.

## `input_type`
For retrieval/RAG, set `input_type` explicitly:
- `query`: Voyage prepends `Represent the query for retrieving supporting documents: `.
- `document`: Voyage prepends `Represent the document for retrieval: `.
- `None`: no prompt. Embeddings with/without `input_type` remain compatible, but docs recommend not omitting for retrieval/search.
Use `query` for user queries and `document` for indexed corpus chunks.

## Similarity
Voyage embeddings are normalized to length 1. Dot product = cosine similarity; dot product is faster. Cosine and Euclidean produce identical rankings.

## Flexible dimensions and quantization
Supported newer models (`voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-code-4`, `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-code-3`) support `output_dimension`: 2048, 1024 default, 512, 256.
- Matryoshka embeddings: leading dimensions form valid shorter embeddings. Can generate 2048 then truncate to first 1024/512/256 and renormalize; or request `output_dimension` directly.
- `output_dtype`:
  - `float`: 32-bit floats, highest precision/accuracy, all models.
  - `int8`: signed 8-bit ints -128..127.
  - `uint8`: unsigned 8-bit ints 0..255.
  - `binary`: bit-packed signed int8 list; length = output_dimension/8; uses offset binary.
  - `ubinary`: bit-packed uint8 list; length = output_dimension/8.
Quantization reduces storage/search cost: int8/uint8 ~4x smaller than float32; binary/ubinary ~32x smaller. Expect small retrieval-quality tradeoff. Many vector DBs support quantized embeddings. For MongoDB Atlas Vector Search, map int8/binary carefully to supported BSON vector subtype/quantization behavior.
`encoding_format:"base64"` returns Base64-encoded NumPy array: float32 for float, int8 for int8/binary, uint8 for uint8/ubinary.

## Contextualized chunk embeddings
Purpose: embed document chunks with both local chunk detail and global context from the entire document, improving long-document retrieval without LLM-generated contextual prefixes/metadata.

### `voyage-context-4` (current recommended model)
- Released 2026-06-29. Current next-generation contextualized chunk model and a drop-in replacement for `voyage-context-3`; it is not preview.
- General-purpose/multilingual model with a MoE backbone. It produces one context-aware vector per chunk: each encodes the chunk and document-level context.
- 32k per-chunk context window; 120k total request input limit; dimensions 1024 default / 256 / 512 / 2048. Supports `float`, `int8`, `uint8`, `binary`, and `ubinary` outputs.
- Built-in auto-chunking and native overlap support. Full documents longer than 32k are transparently split and embedded, so operationally there is no single-document context-window constraint when using its automatic handling.
- Can also serve as a standard single-embedding model, and Voyage reports it as its strongest embedding model to date. On its 39-dataset, eight-domain evaluation: +2.08% average chunk-level and +1.4% document-level retrieval versus context-3; in single-embedding mode, +0.45% versus voyage-4-large and +3.02% versus context-3. LongEmbed contextual chunks improved +7.11% versus single embeddings.
- Use it especially for long contracts, transcripts, manuals, or cases where chunk-to-document context matters. `voyage-4-large` remains an appropriate general-purpose non-contextual choice; for code-specific retrieval use `voyage-code-3`.

### API and usage
```python
result = vo.contextualized_embed(
  model="voyage-context-4",
  inputs=["full doc 1", "full doc 2"],
  input_type="document",
  enable_auto_chunking=True,
  chunk_size=512,       # target; backend may use a smaller actual size
  chunk_overlap=64,     # billed; must be smaller than chunk_size
  output_dimension=1024,
  output_dtype="float"
)
# result.results[i].embeddings, .chunk_texts, .index; result.total_tokens
```
Use cases/input shapes:
- Auto chunking: `inputs: List[str]`, `input_type:"document"`, `enable_auto_chunking:True`, no `chunk_fn`. Prefer this when no established client chunking scheme exists.
- Pre-chunked docs: `inputs: List[List[str]]`, `input_type:"document"`, auto chunking false/omitted. Each inner list = chunks of one document; the model embeds each chunk in its group's context.
- Client-side chunking: `inputs: List[List[str]]` (often one full document per inner list), `chunk_fn=voyageai.default_chunk_fn` or custom, auto chunking false.
- Queries: `inputs: List[str]` or nested single-query lists, `input_type:"query"`, no auto chunking.
Constraints: max 1000 inputs; total tokens <=120k; total chunks <=16k; `chunk_size` <=32k; `chunk_overlap < chunk_size`; overlapping tokens are billed. Invalid: flat `List[str]` documents without auto chunking; auto chunking with non-document input_type; `chunk_fn` with auto chunking.
REST endpoint: `POST /v1/contextualizedembeddings`, request `inputs`, `input_type`, `model`, `enable_auto_chunking`, `chunk_size`, `chunk_overlap`. Response contains nested `data`, chunk `text`, `model`, `usage`, `chunker_version`.

### Legacy `voyage-context-3`
- Same 32k per-chunk/120k total limits and flexible dimensions, but is older and is superseded by context-4. Preserve only for compatibility or an established deployment.

## Multimodal embeddings
Purpose: shared vector space for text + content-rich images/videos; supports interleaved text and visual inputs (PDF screenshots, slides, tables, figures, photos, video frames). Avoids CLIP same-modality bias by single backbone.
Model:
- `voyage-multimodal-3.5`: 32k context, dims 1024 default / 256 / 512 / 2048. Supports text, images, videos, interleaved input.
Older: `voyage-multimodal-3`: 32k, dim 1024, text/images/interleaved (no videos per docs; video only supported by 3.5 in Python docs).
Python:
```python
from voyageai.video_utils import Video
import PIL, voyageai
vo = voyageai.Client()
inputs = [["This is a banana.", PIL.Image.open("banana.jpg"), Video.from_path("banana.mp4", model="voyage-multimodal-3.5")]]
result = vo.multimodal_embed(inputs, model="voyage-multimodal-3.5", input_type="document")
```
Input formats: list of sequences containing strings, PIL Image objects, Video objects; or REST-style dict `{content:[{type:"text", text:"..."}, {type:"image_base64", image_base64:"data:image/...;base64,..."}, {type:"image_url", image_url:"..."}]}`.
Constraints: max 1000 inputs; each image <=16M pixels and <=20MB; each video <=20MB; every 560 image pixels = 1 token, every 1120 video pixels = 1 token; each input <=32k tokens; total tokens <=320k. `truncation=True` truncates over-length input; if truncation cuts inside image, whole image discarded.
Returns: embeddings, text_tokens, image_pixels, total_tokens (and count_usage includes video_pixels). REST endpoint `POST /v1/multimodalembeddings`.
URL constraints from 2025-12-08: URL params (e.g. `image_url`) limit redirects, require `content-length`, respect robots.txt.

## Rerankers
Rerankers are cross-encoders: jointly process query+doc for more accurate relevance than separate embeddings. Use after retrieving top candidates via vector or lexical search.
Models:
- `rerank-2.5`: 32k context, generalist quality, instruction-following, multilingual.
- `rerank-2.5-lite`: 32k context, optimized latency+quality, instruction-following, multilingual.
Older accessible: `rerank-2` 16k, `rerank-2-lite` 8k, `rerank-1` 8k, `rerank-lite-1` 4k.
Python:
```python
reranking = vo.rerank(
  query="When is Apple's conference call scheduled?",
  documents=["doc1", "doc2"],
  model="rerank-2.5",
  top_k=3,
  truncation=True
)
for r in reranking.results:
  print(r.index, r.relevance_score, r.document)
```
REST:
```bash
curl https://api.voyageai.com/v1/rerank \
  -H "Content-Type: application/json" \
  -H "$(printf 'Authorization%s Bearer %s' ':' "$VOYAGE_API_KEY")" \
  -d '{"query":"Sample query","documents":["doc 1","doc 2"],"model":"rerank-2.5-lite","top_k":2,"return_documents":true}'
```
Parameters: `query`, `documents`, `model` required; `top_k`, `return_documents` (REST, default false), `truncation` default true. Python returns documents; REST only returns docs if `return_documents:true`.
Limits: docs <=1000. Query max tokens: 8k for rerank-2.5/2.5-lite; 4k rerank-2; 2k rerank-2-lite/rerank-1; 1k rerank-lite-1. Query + any single doc max: 32k for 2.5/2.5-lite; 16k rerank-2; 8k rerank-2-lite/rerank-1; 4k rerank-lite-1. Total rerank tokens = query_tokens * number_docs + sum(doc_tokens), max 600k for 2.5/2.5-lite/2/2-lite, 300k for rerank-1/lite-1. For latency-sensitive apps, use `rerank-2.5-lite` and <=200k total tokens/request.

## Tokenization
- API tokenizes automatically. Voyage tokenizers available on Hugging Face: `AutoTokenizer.from_pretrained("voyageai/voyage-4-large")`.
- Python: `vo.tokenize(texts, model="voyage-4-large")`, `vo.count_tokens(texts, model="voyage-4-large")`.
- Multimodal: `vo.count_usage(inputs, model="voyage-multimodal-3.5")` returns text_tokens, image_pixels, video_pixels, total_tokens.
- Always specify `model` for tokenizer/counts; newer models use different tokenizers than old Llama2-based models.
- Approximation: 1 word ≈1.2-1.5 tokens; Voyage tokens average ~5 chars; Voyage tokenizer often 1.1-1.2x OpenAI tiktoken count. Use `count_tokens` for exact billing/limit planning.

## Pricing (usage-based)
Text/contextual embeddings: billed by tokens. Free tokens per account: 200M for `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-context-4`, `voyage-code-4`, and `voyage-code-3`; 50M for `voyage-multilingual-2`, `voyage-finance-2`, `voyage-law-2`, and `voyage-code-2`. Legacy models receive no free tokens.
- `voyage-4-large`: $0.12/M tokens.
- `voyage-4`: $0.06/M.
- `voyage-4-lite`: $0.02/M.
- `voyage-context-4`: $0.12/M.
- `voyage-code-4`: $0.12/M tokens (one-third below code-3; first 200M tokens free).
- `voyage-code-3`: $0.18/M.
- Legacy `voyage-context-3`: $0.18/M, no free tokens.
- `voyage-finance-2`, `voyage-law-2`, `voyage-code-2`: $0.12/M.
Multimodal: `voyage-multimodal-3.5` and `voyage-multimodal-3`: first 200M text tokens +150B pixels free. Then $0.12/M tokens + $0.60/B pixels. Images under 50k pixels charged as 50k; over 2M pixels downsampled/charged as 2M. Min/max per image: $0.00003 / $0.0012.
Rerankers: first 200M tokens free for `rerank-2.5`, `rerank-2.5-lite`, `rerank-2`, `rerank-2-lite`. Then `rerank-2.5` $0.05/M, `rerank-2.5-lite` $0.02/M.
Batch API: 12h completion window, 33% discount vs standard endpoints; free-token credits do not apply to Batch usage. Files API storage $0.05/GB/month, files retained 30 days. Older model pricing differs/no free tokens. Fine-tuned dedicated models: contact sales.
Billing monthly; payment method in dashboard. Prepaid credits available, expire after 1 year, non-refundable.

## Rate limits
Basic org limits:
- The current rate-limits page (checked 2026-07-28) does not list `voyage-context-4`; do not infer its limit from context-3. Verify the customer/org dashboard or Voyage support for its applicable limit.
- `voyage-4-large`, `voyage-3-large`, `voyage-context-3`, `voyage-code-3`, voyage 1&2 embedding models: 3M TPM, 2000 RPM.
- `voyage-4`, `voyage-code-4`, `voyage-3.5`: 8M TPM, 2000 RPM.
- `voyage-4-lite`, `voyage-3.5-lite`: 16M TPM, 2000 RPM.
- `voyage-multimodal-3.5`, `voyage-multimodal-3`: 2M TPM, 2000 RPM.
- `rerank-2.5-lite`, `rerank-2-lite`, `rerank-lite-1`: 4M TPM, 2000 RPM.
- `rerank-2.5`, `rerank-2`, `rerank-1`: 2M TPM, 2000 RPM.
Usage tiers: Tier 1 requires payment method = basic. Tier 2 after >=$100 paid = 2x Tier 1. Tier 3 after >=$1000 paid = 3x Tier 1. Tier based on billed usage excluding free tokens; never downgraded. Request increase if Tier 3 insufficient. Project-level limits can be set <= org model limit; org limit can still throttle projects if aggregate exceeds org.
Avoid 429: larger embedding batches (within request limits), pacing/sleep, exponential backoff with jitter, `max_retries`, batch API for offline work, request rate increase.

## Batch API (Public Preview)
Use for large offline embedding/reranking/eval workloads. Supports `/v1/embeddings`, `/v1/contextualizedembeddings`, `/v1/rerank`. 12h completion window, retries/threading managed, 33% discount. Jobs tied to project of API key.
Flow:
1. Create JSONL input file. Each line: `{"custom_id":"unique", "body":{...endpoint input...}}`. `custom_id` maps outputs to inputs; output order not guaranteed. Body uses `input` for embeddings, `inputs` for contextualized, `query`+`documents` for rerank. Model/params set at batch level.
2. Upload file: `POST /v1/files` multipart `purpose=batch`, `file=@foo.jsonl`; get `file_id`.
3. Create batch: `POST /v1/batches` with `endpoint`, `completion_window:"12h"`, `request_params:{model,...}`, `input_file_id`, optional `metadata` max 16 key-values.
4. Poll retrieve batch: `GET /v1/batches/{id}`.
5. Download `output_file_id` via `GET /v1/files/{file_id}/content`; failures in `error_file_id`.
6. Cancel: `POST /v1/batches/{id}/cancel`; cancellation up to 10 min; completed partial results billed/available; no penalty.
Limits: max 100k inputs/batch; each embedded request still has endpoint batch/context/token limits; org max 100 in-flight batch jobs and 1B tokens across in-flight jobs. Statuses: validating, failed, in_progress, finalizing, completed, cancelling, cancelled; may partially complete on completion-window expiry and write unfinished requests to error file. The current Batch model-availability list includes `voyage-context-3` but does not list `voyage-context-4`; do not promise Batch API support for context-4 without a current verification. Other listed models: `voyage-4-large`, `voyage-4`, `voyage-4-lite`, `voyage-3-large`, `voyage-3.5`, `voyage-3.5-lite`, `voyage-code-4`, `voyage-code-3`, `voyage-code-2`, `rerank-2.5`, `rerank-2.5-lite`.

## Organizations/projects/security/data
- Organization = top-level billing/budget/data controls/rate limits/API keys; projects = sub-group resources/settings/team/use case. API keys and batch jobs belong to projects.
- Roles: Org Admin full org control; Project Owner full project control; Member can create keys for projects they belong to and view allowed resources.
- Data control: For Voyage-hosted endpoints, customers can opt out of data storage/use for future model training for zero-day retention. Requires payment method and Org Admin; dashboard Terms of Service toggle. Cannot opt back in via dashboard; contact legal.
- SLO: `api.voyageai.com` and dashboard target >=99.5% monthly uptime. Status page: https://voyageai-status.statuspage.io.

## Error codes
- 400 Invalid Request: bad JSON, invalid/wrong-type parameter, batch too large, token limit/context exceeded. Fix request.
- 401 Unauthorized: invalid/missing API key. Check Authorization header/key/dashboard.
- 403 Forbidden: IP address might be forbidden. Try different IP/contact support.
- 429 Rate Limit Exceeded: too many requests/tokens. Pace, batch, backoff, increase limits.
- 500 Server Error: retry after brief wait; contact if persistent.
- 502/503/504 Service Unavailable: high traffic; retry after brief wait.

## Integrations
Documented integrations include MongoDB Atlas Vector Search / MongoDB Automated Embedding, DataStax Astra DB, Epsila, Haystack, LanceDB, LangChain, LlamaIndex, MyScale, pgai, Redis, Unstructured, Vectorize, Weaviate, Zilliz, IBM, Milvus, Pinecone, Qdrant. Python client works with most vector DB libraries.
MongoDB-specific integration details:
- **Native `$rerank` aggregation stage** (preview, MongoDB 8.3+, Atlas-only, not self-managed/local): reranks pipeline documents in-pipeline using Voyage rerankers; enable Native Reranking in Atlas Project Settings. Models: `rerank-2.5`, `rerank-2.5-lite`, `rerank-2`, `rerank-2-lite`. See atlas_vector_search skill for full syntax.
- **Atlas Embedding and Reranking API (GA, announced 2026-08-13)**: database-agnostic serverless REST API for Voyage retrieval models hosted by MongoDB, usable from MongoDB or non-MongoDB applications. Rerank endpoint: `https://ai.mongodb.com/v1/rerank`. Auth via Atlas-managed model API keys (not Voyage API keys). Verify the current Atlas AI API documentation for embedding endpoint/model availability and token pricing before giving exact details.

## Answering guidance
- For RAG: embed corpus chunks with `input_type="document"`, store in vector DB (MongoDB recommended), embed user query with `input_type="query"`, retrieve top-k, optionally rerank with `rerank-2.5`/lite, pass top chunks to LLM. On MongoDB Atlas 8.3+ (preview), rerank in-pipeline with the native `$rerank` aggregation stage instead of calling the API separately; or use the Atlas Embedding and Reranking API (`https://ai.mongodb.com/v1/rerank`) for standalone usage.
- For best general retrieval quality: `voyage-4-large` + rerank-2.5. For cost/latency: `voyage-4-lite` + rerank-2.5-lite or skip rerank. For code and coding agents: `voyage-code-4` (preferred over code-3 for new deployments). For long documents or retrieval requiring document-wide chunk context: use current `voyage-context-4` (prefer its auto-chunking unless an established chunker requires otherwise); use context-3 only for legacy compatibility. For images/slides/PDF screenshots: `voyage-multimodal-3.5`.
- For MongoDB Atlas Vector Search: use `dotProduct` or `cosine` (rank equivalent); dot product faster since Voyage vectors normalized. Match Atlas `numDimensions` to `output_dimension`. Consider quantization/BinData tradeoffs.
- For API examples: prefer Python `voyageai.Client` or REST curl snippets above.

Redaction report

• redacted 1 match(es) for (?i)(api[_-]?key|secret|token|password|passwd
• redacted 5 match(es) for (?i)(api[_-]?key|secret|token|password|passwd