Use cases
What AI-native teams build on one endpoint.
Unified Inference is for engineering teams that treat the model as a setting rather than a dependency. Six jobs it does, each one a base-URL change away — from swapping the model behind a feature to running Claude Code on Kimi.
- OpenAI + Anthropic formats
- Stable model aliases
- One organization balance
- Pay as you go
Ship features that outlive the model behind them.
Write the integration once, against the format your code already speaks. After that the model is configuration: a short alias in the request body, changed per feature, per customer, or per environment without touching the call site or redeploying a client.
The awkward part of a model swap is usually not the swap — it is the
parameter surface moving under you. Unsupported generation parameters
are dropped and out-of-range values clamped instead of 400-ing, and
every change is named in a response header, so you find out from
X-MindsHub-Dropped-Params rather than from a customer.
POST /v1/embeddings is on the same key, so retrieval does
not need a second vendor.
from openai import OpenAI
client = OpenAI(
base_url="https://api.mindshub.ai/v1",
api_key=os.environ["MINDSHUB_API_KEY"],
)
# The only line that changes when the model does.
MODEL = "sonnet" # "gpt" | "kimi" | "deepseek" | "haiku"
client.chat.completions.create(model=MODEL, messages=messages)24 of 24 models in the live catalog publish an ordered fallback chain. Claude Haiku 4.5 falls back to Gemini 3.7 Flash → DeepSeek V4-Pro-0813. Per model, not universal — every model lists one today, and chains can change. Every chain is on the rate card.
Point the agents you already run at any model.
Most agents have a field for an API key and a base URL, and those two fields are the whole integration: put MindsHub's in and the agent keeps working exactly as it did, on any model in the catalog, with every request landing in one organization usage summary and on one bill.
That covers the agent you built in-house, the one your vendor lets you configure, and every agentic CLI with a base-URL setting. The models are short aliases, so which one an agent runs on is a one-string change — and the same key works whether the agent speaks the OpenAI or the Anthropic request format.
And the coding CLIs, where those two fields are buried in per-tool config and environment variables? You can point those too — you just shouldn't have to do it by hand. SetFree is our MIT-licensed tool for exactly that: a configuration wrapper rather than a fork, it launches the real Claude Code, Codex or VS Code with the gateway already in the environment and passes your arguments through untouched. One command instead of a setup hunt, and the whole team's agent traffic lands on one key.
Claude Code, Codex and VS Code work through SetFree today. Gemini CLI
and Aider are detected but wait on an adapter, and first run is
interactive unless SETFREE_BASE_URL and
SETFREE_API_KEY are already set — which is the path to
use in CI.
# 1 — install (macOS / Linux; Windows has a PowerShell one-liner)
curl -fsSL https://raw.githubusercontent.com/mindsdb/setfree/main/install.sh | sh
# 2 — point it at MindsHub, once
# (or set SETFREE_BASE_URL + SETFREE_API_KEY, e.g. in CI)
setfree config
# 3 — launch the agent you already use, on any model
setfree claude # Claude Code
setfree codex . # Codex
setfree code . # VS Code, with the gateway in its envOne key, one balance, one place to see the spend.
An AI-native team accumulates accounts fast: a provider per model, a key per engineer, a card per tool, and no single answer to what last month cost. Consolidating on one endpoint replaces that with one organization balance and one usage summary — for your product traffic and your agents' traffic alike.
MindsHub Cowork already runs on it. The Model Router is pre-wired into the workspace, so nobody sets up a provider key to start working, and what the workspace spends shows up in the same summary next to everything else.
- One prepaid balance Top up when you want, or turn on auto-recharge with a cap on how much it can charge each month.
- One usage summary Every API request and every agent request lands in the same organization summary, grouped by model.
- Keys issued in the console One place to hand a key out and one place to see what it spent.
- GET /v1/models is authoritative It reports the live catalog and whether each model is enabled for your organization.
Run the bake-off before you pick a favourite.
The honest way to choose a model is to run your own eval set through several and compare. The reason teams skip it is setup cost: separate accounts, separate SDKs, separate invoices, and no way to line the results up against what each one actually cost.
Here the loop is the alias. Same client, same request body, one string per iteration — and because per-model spend is broken out in a single usage summary, the quality table and the cost table describe the same run. That matters more than the sticker price: cost per task, not price per token, is what predicts the bill.
EVAL = load_cases("./evals/support-triage.jsonl")
for model in ["sonnet", "gpt", "kimi", "deepseek"]:
for case in EVAL:
r = client.chat.completions.create(
model=model, messages=case.messages,
)
score(model, case, r)
# One key, one bill — and the usage summary breaks spend out
# per model, so the quality table and the cost table describe
# the same run.Make the agent loop stop paying full price.
An agent turn resends the same prefix every time: system prompt, tool definitions, and the whole conversation so far. Left alone, that prefix is the largest line on the bill and it grows with the session.
Prompt caching is automatic on most of the catalog, and cached input
bills at roughly a tenth of the ordinary input rate — so the second
turn onward costs a fraction of the first. Claude-family models use
cache_control breakpoints on Messages. Input, output,
cached input and cache writes are metered separately, which is what
makes the saving visible rather than theoretical.
The other half is routing: send routine steps to open models and keep the frontier ones for the hard parts. One integration, so that decision stays a string rather than a refactor.
Keep history client-side and send it each turn — conversation chaining is not honored, and caching is what makes that cheap.
If it lets you set a base URL, it works.
The agents are the case above; this is everything else. Most of the AI surface in a startup is not the product at all: the workflow-automation node, the IDE extension, the agent framework, the internal script that summarises tickets overnight, the third-party app that asks for an OpenAI key.
Anything that accepts a base URL and a key can point here, and three
request formats reach the same catalog, the same balance and the same
usage summary. Which one you use is a property of the tool, not a
decision you have to make: OpenAI-format clients use the
/v1 base URL with an api_key field, while
Anthropic-format clients use the bare host with auth_token
instead.
OpenAI-format SDKs and tools
base URL https://api.mindshub.ai/v1
auth api_key
Anthropic-format SDKs and tools
base URL https://api.mindshub.ai (no /v1)
auth auth_token -> Authorization: BearerThe questions that decide it.
- Do I have to change code to switch models?
- No. Models are referenced by short, stable aliases, so switching is a one-string change — and the alias keeps working when the underlying model is upgraded. Unsupported generation parameters are dropped and out-of-range values clamped rather than rejected, with every change named in the X-MindsHub-Dropped-Params and X-MindsHub-Clamped-Params response headers, so a swap does not turn into a 400 hunt.
- What happens if a model is unavailable?
- Failover is per model, not universal: the catalog publishes an ordered fallback chain for each model that has one, and some models list none. The rate card on the pricing page shows every chain, so you can see exactly what a given model falls back to before you depend on it.
- How do I point an agent at MindsHub?
- If the agent lets you set an API key and a base URL, that is the whole integration — no wrapper, no fork, no code change. For the popular coding CLIs that hard-code their provider, SetFree is MIT-licensed open source from the MindsDB team and a configuration wrapper rather than a fork: it launches the real Claude Code, Codex or VS Code with a gateway in the environment. Those three work today; Gemini CLI and Aider are detected but wait on an adapter. First run is interactive unless SETFREE_BASE_URL and SETFREE_API_KEY are already set, which is the path to use in CI.
- Does conversation state live on your side?
- No. Keep conversation history client-side and send the full history on each turn. Prompt caching is what makes that cheap on most of the catalog; previous_response_id and store are accepted but not honored.
- Will my streaming and tool-calling code keep working?
- Yes. Each protocol keeps its own native event shape, so existing stream parsers keep working on Chat Completions and Messages, and each keeps its own completion and failure signals. Function tools, image input and built-in web search are supported where the selected model and request format support them.
- Can I bring my own provider key?
- Not today. Bring-your-own-key is planned, not available: the current service uses one MindsHub key and one organization wallet. The workspace is the exception — MindsHub Cowork lets you paste in provider keys and pay those providers directly.