Mixedbread

TypeScript SDK

API reference for Mixedbread's Embeddings endpoint. This documentation covers request parameters, authentication requirements, and response structure for generating vector representations of text inputs.

Installation
npm install @mixedbread-ai/sdk

Quick Start

Here's a quick example to get you started with the API:

Client creation
import { MixedbreadAIClient } from "@mixedbread-ai/sdk";
 
const mxbai = new MixedbreadAIClient({
    apiKey: "YOUR_API_KEY",
    maxRetries: 3,
});

Reranking documents

Reranking example
const model = "mixedbread-ai/mxbai-rerank-large-v1";
const query = "What's the best way to make sourdough bread?";
const documents = [
    "Sourdough bread is made using a fermented dough starter instead of commercial yeast. The process typically takes 24-48 hours and results in a tangy, chewy bread with a crisp crust.",
    "Croissants are a French pastry made from layered, buttery, yeast-leavened dough. They are known for their flaky texture and crescent shape.",
    "To make sourdough bread, you'll need a mature sourdough starter, bread flour, water, and salt. The key is to allow enough time for fermentation and proper shaping techniques.",
    "Baguettes are a long, thin loaf of French bread known for their crispy crust and chewy interior. They're typically made with just flour, water, yeast, and salt.",
    "The best way to make sourdough bread involves maintaining a healthy starter, using a high-quality bread flour, and mastering the techniques of folding and shaping the dough. Proper fermentation time and baking in a Dutch oven can greatly improve results.",
    "Rye bread is a type of bread made with various proportions of rye flour. It has a stronger, more distinctive flavor than bread made from wheat flour and is popular in many parts of Europe."
];
 
const rerankedDocs = await mxbai.reranking({
    model,
    query,
    input: documents
});
 
console.log(rerankedDocs);

Embedding documents

Embedding example
const model = "mixedbread-ai/mxbai-embed-large-v1";
 
// Query embedding (with prompt)
const queryEmbedding = await mxbai.embeddings({
    model,
    input: ["What's the secret to making fluffy croissants?"],
    prompt: "Represent this question for searching relevant bakery passages:"
});
 
// Document embeddings (without prompt)
const documents = [
    "Croissants are made by layering butter and dough through a process called lamination.",
    "The key to fluffy croissants is using cold butter and maintaining a cool temperature throughout the folding process.",
    "Sourdough bread requires a starter culture made from flour and water.",
    "Baguettes are best baked in a steam-filled oven for a crispy crust.",
    "Fluffy croissants need multiple rounds of folding and chilling to create many layers."
];
 
const documentEmbeddings = await mxbai.embeddings({
    model,
    input: documents
});
 
console.log({ queryEmbedding, documentEmbeddings });

Configuration

The MixedbreadAIClient constructor accepts the following options:

interface MixedbreadAIClientOptions {
    apiKey: string;
    maxRetries?: number;
    timeout?: number;
    baseURL?: string;
}
  • apiKey: Your Mixedbread API key (required)
  • maxRetries: Maximum number of retries for failed requests (default: 3)
  • timeout: Request timeout in milliseconds (default: 30000)
  • baseURL: Custom base URL for API requests (optional)

Error Handling

Use try/catch blocks to handle errors:

import { MxbaiApiError } from "@mixedbread-ai/sdk";
 
try {
    const embeddings = await mxbai.embeddings({
        model: "mixedbread-ai/mxbai-embed-large-v1",
        input: ["Example text"],
    });
} catch (err) {
    if (err instanceof MxbaiApiError) {
        console.error(`API Error: ${err.message}`);
        console.error(`Status Code: ${err.statusCode}`);
    } else {
        console.error(`Unexpected error: ${err}`);
    }
}

Next Steps

Happy baking! 🍞🚀

On this page