Python SDK

Introduction

The Mixedbread Python SDK provides a convenient interface for accessing our API with built-in error handling, retries, and type safety.

Requirements: Python 3.8+ required. For older versions, consider using our REST API directly.

Installation

Install the SDK using pip:

Installation

pip install mixedbread

For development with the latest features:

Development Installation

pip install mixedbread[dev]

Quick Start

Get started with a simple example:

Basic Usage

import os
from mixedbread import Mixedbread
 
# Initialize client with API key
mxbai = Mixedbread(api_key=os.getenv("MIXEDBREAD_API_KEY"))
 
# Generate embeddings
embeddings = mxbai.embed(
    model="mixedbread-ai/mxbai-embed-large-v1",
    input=["Hello, world!", "How are you?"]
)
 
print(f"Generated {len(embeddings.data)} embeddings")

Configuration

The Mixedbread constructor accepts the following parameters:

class Mixedbread:
    def __init__(
        self,
        api_key: str,
        max_retries: int = 3,
        timeout: float = 30.0,
        base_url: str = "https://api.mixedbread.com"
    ):
        # ...

api_key: Your Mixedbread API key (required)
max_retries: Maximum number of retries for failed requests (default: 3)
timeout: Request timeout in seconds (default: 30.0)
base_url: Custom base URL for API requests (default: https://api.mixedbread.com)

Async Support

For async applications, use the async client:

Async client

from mixedbread import AsyncMixedbread
 
async_mxbai = AsyncMixedbread(api_key="YOUR_API_KEY")

Error Handling

Use try/except blocks to handle errors:

from mixedbread.exceptions import MixedbreadError, RateLimitError
 
try:
    embeddings = mxbai.embed(
        model="mixedbread-ai/mxbai-embed-large-v1",
        input=["Example text"]
    )
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
except MixedbreadError as e:
    print(f"API Error: {e}")
    print(f"Status Code: {e.status_code}")
except Exception as e:
    print(f"Unexpected error: {e}")

Available Services

The SDK provides access to all Mixedbread API endpoints:

Service	Description	Example Usage
`mxbai.embed()`	Generate text embeddings	`mxbai.embed(model="...", input=["text"])`
`mxbai.rerank()`	Rerank document lists	`mxbai.rerank(query="...", documents=[...])`
`mxbai.vector_stores`	Manage vector stores	`mxbai.vector_stores.create(name="...")`
`mxbai.vector_stores.files`	Manage store files	`mxbai.vector_stores.files.create(...)`
`mxbai.files`	Upload and manage files	`mxbai.files.create(file=file_obj)`
`mxbai.parsing.jobs`	Parse documents	`mxbai.parsing.jobs.create(file_id="...")`

Environment Setup

Using Environment Variables

Environment Configuration

# Set your API key
export MIXEDBREAD_API_KEY="your_api_key_here"
 
# Optional: Custom base URL
export MIXEDBREAD_BASE_URL="https://api.mixedbread.com"

Environment-based Initialization

import os
from mixedbread import Mixedbread
 
# Automatically uses MIXEDBREAD_API_KEY environment variable
mxbai = Mixedbread()
 
# Or specify explicitly
mxbai = Mixedbread(
    api_key=os.getenv("MIXEDBREAD_API_KEY"),
    base_url=os.getenv("MIXEDBREAD_BASE_URL", "https://api.mixedbread.com")
)

Resources

Documentation

API Reference - Complete endpoint documentation
GitHub Repository - Source code and examples
PyPI Package - Package details and release notes

Support

Discord Community - Get help and share projects
GitHub Issues - Report bugs and request features
API Dashboard - Manage your API keys and usage

Happy building with Python! 🐍🍞

SDKs

Access Mixedbread's API with our easy-to-use SDKs for Python and TypeScript.

TypeScript SDK

Learn how to install and configure Mixedbread's TypeScript SDK for interacting with our API services.

Last updated: June 11, 2025