Accessing Voyage AI Models

API Keys

The Embedding and Reranking API uses API keys to monitor usage and manage permissions. To create and manage your model API keys, use the MongoDB Atlas UI. For instructions, see Manage Voyage AI Model API Keys.

REST API

The following examples demonstrate how to call the embedding service through the REST API. The API supports cURL and HTTP requests from any programming language.

Authentication is handled through the model API Key, which you must include in the authorization header of every API request as a Bearer token.

To learn more, see the full API specification.

https://eu.ai.mongodb.com/v1/embeddings

Python Client

To install the official Python package using pip:

pip install --upgrade voyageai

Use the --upgrade or -U option to install the latest version of the package. This gives you access to the most recent features and bug fixes. For model-specific parameters, see the usage examples for each model page.

The voyageai.Client class provides a synchronous interface to invoke Voyage's API. Create a client object and use it to access Voyage AI models.

import voyageai
# Initialize the client with custom settings
vo = voyageai.Client(
    api_key="<model-api-key>",  # Or use VOYAGE_API_KEY environment variable
    max_retries=3,              # Retry up to 3 times on rate limit errors
    timeout=30                  # Timeout after 30 seconds
)
# Generate embeddings
result = vo.embed(
    texts=["MongoDB is redefining what a database is in the AI era."],
    model="voyage-4-large"
)
print(f"Embedding dimension: {len(result.embeddings[0])}")
print(f"Total tokens used: {result.total_tokens}")

The following table describes the parameters you can pass when initializing the client:

TypeScript Client

To install the official TypeScript package using npm:

npm install voyageai

The VoyageAIClient class provides an asynchronous interface to invoke Voyage's API from TypeScript and JavaScript applications. Create a client object and use it to access Voyage AI models.

Unlike the Python client, the TypeScript client sends requests to the Voyage platform endpoint (https://api.voyageai.com/v1) by default. To use the Embedding and Reranking API with your model API key, set the environment option to https://ai.mongodb.com/v1 when you create the client.

import { VoyageAIClient } from "voyageai";
// Initialize the client for the Embedding and Reranking API
const client = new VoyageAIClient({
  apiKey: process.env.VOYAGE_API_KEY,     // Model API key
  environment: "https://ai.mongodb.com/v1",
  maxRetries: 3,                          // Retry up to 3 times
  timeoutInSeconds: 30                    // Time out after 30 seconds
});
// Generate embeddings
const result = await client.embed({
  input: ["MongoDB is redefining what a database is in the AI era."],
  model: "voyage-4-large"
});
console.log(`Embedding dimension: ${result.data[0].embedding.length}`);
console.log(`Total tokens used: ${result.usage.totalTokens}`);

The following table describes the options you can pass when initializing the client:

In addition to embed, the client provides the rerank, multimodalEmbed, and contextualizedEmbed methods. For model-specific parameters, see the usage examples for each model page.