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?

Set the MindsHub base URL and API key in any agent that supports both. For Claude Code, Codex, and VS Code, the open-source SetFree tool adds the gateway configuration without forking the original tool. Gemini CLI and Aider adapters are not available yet.

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. Chat Completions and Messages keep their native streaming events and error signals. Tools, image input, and web search work where the chosen 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.

Use cases

Six practical uses for one model API.

Switch models, connect agents and tools, compare results, and keep usage on one organization account.

Get an API key Start with the docs

OpenAI + Anthropic formats
Stable model aliases
One organization balance
Pay as you go

Switch models in your product
Connect agents and coding tools
Consolidate team usage
Compare models on your work
Reduce repeated-prompt costs
Connect compatible tools

01 · In your product

Switch models without rewriting the feature.

Integrate once using OpenAI or Anthropic request formats. After that, change the short model alias per feature, customer, or environment.

Unsupported parameters are dropped and out-of-range values are clamped. Response headers list the changes. Embeddings use the same key through POST /v1/embeddings.

Aliases and GET /v1/models → See the rate card →

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)

27 of 27 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.

02 · Your agents

Run your agents on the model you choose.

If an agent accepts a base URL and API key, point both at MindsHub. Its requests then use the same catalog, balance, and usage summary as the rest of your software.

For Claude Code, Codex, and VS Code, SetFree adds the gateway configuration and launches the original tool. It is MIT-licensed and does not fork those clients.

Gemini CLI and Aider adapters are not available yet. For CI, set SETFREE_BASE_URL and SETFREE_API_KEY before the first run.

SetFree on GitHub → The Messages format Claude Code speaks →

# 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 env

03 · For the team

Put team usage on one account.

Use one organization balance and usage summary for product and agent traffic. The summary groups usage by model.

MindsHub Cowork uses the same account, so workspace usage appears beside API traffic.

Usage and wallet docs → Model rates →

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.

04 · Model selection

Compare models on your own tasks.

Run the same evaluation set through several models without creating a separate account or integration for each provider.

Change one alias per run, then compare the outputs with the per-model costs in the usage summary.

Shortlist from the rankings → What each model is good at → Why cost per task is the number →

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.

05 · Economics

Pay less for repeated context.

Agents resend the system prompt, tool definitions, and conversation history on every turn. That repeated prefix grows with the session.

Prompt caching is automatic on most of the catalog. Cached input is billed at roughly a tenth of the normal input rate. Claude models use cache_control breakpoints with the Messages API.

You can also route routine steps to cheaper models and reserve more capable models for harder work.

How caching is billed → Cached-input rates →

Repeated prefix, three turns Metered

Request 01 System prompt + tools + history input + cache write

Request 02 Same prefix, one more turn ~1/10 input rate

Request 03 Same prefix, one more turn ~1/10 input rate

Keep history client-side and send it each turn — conversation chaining is not honored, and caching is what makes that cheap.

06 · Everything else

Connect tools that accept a base URL.

Point compatible workflow tools, IDE extensions, frameworks, scripts, and third-party apps at the MindsHub endpoint.

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. Both reach the same catalog and balance.

Which API should I use? → Working examples →

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: Bearer

FAQ

Questions about these integrations.

Do I have to change code to switch models?: No. Change the short model alias in the request body. Unsupported parameters are dropped and out-of-range values are clamped; response headers list every change.
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?: Set the MindsHub base URL and API key in any agent that supports both. For Claude Code, Codex, and VS Code, the open-source SetFree tool adds the gateway configuration without forking the original tool. Gemini CLI and Aider adapters are not available yet.
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. Chat Completions and Messages keep their native streaming events and error signals. Tools, image input, and web search work where the chosen 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.