Python SDK

Complete reference for the blobrouter package — bytes, file-like uploads, retries, and errors.

BlobRouter v0.1 · Last updated: August 2026 · Architecture version: 2.0

Python client for the same control-plane API as the TypeScript SDK. Server-side only — keep API keys out of browsers and notebooks that sync publicly.

Install

pip install blobrouter

Constructor

from blobrouter import BlobRouter

storage = BlobRouter(
    api_key="br_live_xxx",
    base_url="https://api.blobrouter.com",  # optional
    max_retries=3,  # optional, default 3
)

Argument	Default	Description
api_key	required	br_live_… / br_test_…
base_url	https://api.blobrouter.com	API origin
max_retries	3	Control-plane retries

upload(...)

Accepts bytes or file-like IO[bytes].

import os
from blobrouter import BlobRouter

storage = BlobRouter(api_key=os.environ["BLOBROUTER_API_KEY"])

with open("model_checkpoint.pt", "rb") as f:
    result = storage.upload(
        file=f,
        file_name="model_checkpoint.pt",
        content_type="application/octet-stream",
        file_size_bytes=os.path.getsize("model_checkpoint.pt"),
        priority="archive",
    )

print(result["file_id"], result["provider"], result["saved_vs_aws"])

Returns a dict:

Key	Type
file_id	str
url	str
provider	str
saved_vs_aws	float
routing_warning	str (optional)

Routing warnings are also emitted via Python’s warnings.warn().

Retry behavior

Same policy as TypeScript: retry API calls on network / 5xx / 408 / 429; never retry other 4xx; never retry the provider PUT.

PyTorch checkpoint example

import io
import os
import torch
from blobrouter import BlobRouter

storage = BlobRouter(api_key=os.environ["BLOBROUTER_API_KEY"])

buffer = io.BytesIO()
torch.save(model.state_dict(), buffer)
buffer.seek(0)

result = storage.upload(
    file=buffer,
    file_name="checkpoint_epoch_10.pt",
    content_type="application/octet-stream",
    file_size_bytes=buffer.getbuffer().nbytes,
    priority="archive",
)
print(result["file_id"], result["saved_vs_aws"])

get(file_id) / delete(file_id)

got = storage.get(result["file_id"])
print(got["url"], got["expires_at"])

storage.delete(result["file_id"])

Errors

from blobrouter import BlobRouter, BlobRouterError

try:
    storage.upload(...)
except BlobRouterError as err:
    print(err, err.code, err.status_code)

Priority values

Priority	Typical route
hot	Cloudflare R2
cold	Cost formula
archive	Backblaze B2