Docs
Two ways to connect, eight clients covered
FreeModel is an AI model gateway. One API key reaches 477 models across dozens of providers, routed by task, trying free capacity first and falling back to paid when that runs out. It speaks both the OpenAI and Anthropic API shapes, so an existing client points at it without a translation layer.
Which shape you use depends on your client: an MCP server for Claude Code, a base URL for everything that lets you set one. Both end up at the same router.
Pick your client
| Client | How it connects | Config goes in |
|---|---|---|
| Claude Code | MCP server | ~/.claude/mcp.json |
| Codex CLI | OpenAI base URL | Environment variables |
| Cursor | OpenAI base URL | .cursor/settings.json |
| Cline | OpenAI base URL | VS Code settings |
| Continue.dev | OpenAI base URL | config.json |
| Python SDK | OpenAI base URL | Client constructor |
| Node SDK | OpenAI base URL | Client constructor |
| Raw HTTP | Either | Whatever you write |
The two endpoints
| Endpoint | Speaks | Use it for |
|---|---|---|
https://freemodel.online/v1 | OpenAI Chat Completions | Codex CLI, Cursor, Cline, Continue, the OpenAI SDKs, anything with an openai provider mode |
https://freemodel.online/api/gateway | Anthropic Messages | Clients that take an ANTHROPIC_BASE_URL |
The two paths differ because the clients append different things. An OpenAI client appends
/chat/completions, which is why that base already carries /v1. An
Anthropic client appends /v1/messages, so its base stops at
/api/gateway. Pasting one into the other's setting gives you a
/v1/v1/... path and a 404 — the most common mistake setting this up.
Getting a key
Both routes need one. Sign in to the console, open
My → API Keys, and create one. Keys start with sk-.
You can read the model list without a key at all — /v1/models is public,
which is worth doing before you sign up if you want to check coverage first.
The ten-second version
# 1. is the gateway up? no key needed — this checks reachability, not auth
curl -s https://freemodel.online/v1/models | head -c 120
# 2. a real call, which does check your key
curl -X POST https://freemodel.online/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-key" \
-d '{"model":"auto/best-chat","messages":[{"role":"user","content":"Hello"}]}'When something does not work
| Symptom | Most likely cause |
|---|---|
| 404 on every call | The base URL has a duplicated path segment — check for /v1/v1 |
| 401 | Key missing, mistyped, or revoked. The Bearer prefix is required on the OpenAI endpoint |
| 402 | Out of points. Pricing → |
| 429 | Rate limited by the client's own settings rather than the router; slow it down |
| Model not found | The id is not in /v1/models. Combination routes must match exactly, including the auto/ prefix |
When not to use FreeModel
Nothing below is a limitation you can configure around. If any of them applies, a different gateway is the right answer — see the alternatives.
| If you need | Then |
|---|---|
| A specific model we do not serve | Check /v1/models first — we cover 120, not every model that exists |
| Requests never leaving your network | Self-host instead. Requests through FreeModel pass through our gateway by definition — LiteLLM is the open-source option |
| Team budgets, audit logs, SSO | That governance layer does not exist here — Portkey or similar |
| Compliance certifications (SOC 2, HIPAA) | We publish none. Procurement will stop here |
| A paid path you can budget against with a published fee | Our routing is free-first; predictable volume billing is not what this is |