Quickstart — Starting Fresh
.env and run npm install && npm start — you'll be chatting in under five minutes. The default model is free, so it costs nothing, and the same app swaps to OpenRouter with two config values.
Download & run demo from GitHub
Step 1 — Pick one or more gateways
FreeRouter is bring-your-own-keys (BYOK): you hold the accounts and pay the gateways directly — FreeRouter just routes across them. You only need one gateway to start, but routing gets interesting with two (failover or a cost blend). Any of these is a solid first pick:
| Gateway | Why pick it | Get a key |
|---|---|---|
| OpenRouter | Broadest model catalog; a common default primary. Keys live under its Keys page. | openrouter.ai/keys |
| Vercel AI Gateway | Fast setup if you already deploy on Vercel; a strong failover partner. Create a key from the AI Gateway API Keys page. | vercel.com/ai-gateway |
| Cloudflare AI Gateway | Edge gateway with caching and rate limiting. You'll also note your account ID and gateway name. | Get started guide |
More options — OrcaRouter, Requesty, Concentrate, LLM Gateway, Baseten, Darkbloom, Sail, Ramp Router, Together AI, Fireworks AI, Morph, Cheaper Inference, Celeris — are on the Providers page. Create an account on your chosen gateway(s), generate an API key on each, and keep those keys handy for the next step.
Step 2 — Account, provider keys, FreeRouter key
Step 3 — Choose the routing rule
The new key starts with a priority rule over the providers you ticked. For your first key, either rule works — pick based on how many providers you added:
Put your provider first in a priority rule. When you add a second gateway later, append it as a backup — no code changes.
A %-split rule spreads traffic across both gateways so you can compare cost, latency, and quality from day one.
The full reference — weights, failover behavior, and canary patterns — is on the Routing Rules page. Hit the key card's Test key button to send one tiny live completion through the rule before you write code.
Step 4 — Integrate with your code
Point any OpenAI-compatible client at https://api.freerouter.com/v1 with your fr_live_... key. Start with openrouter/free (answers on an unfunded OpenRouter account); once the gateway has credit, pass any provider/model id it lists, such as openai/gpt-4o-mini — your routing rule decides which gateway actually serves it.
Already running the sample chatbot from the top of this guide? You've done this step — skip ahead to Step 5.
curl
export FREEROUTER_API_KEY="fr_live_your_key_here"
curl https://api.freerouter.com/v1/chat/completions \
-H "Authorization: Bearer $FREEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openrouter/free",
"messages": [
{ "role": "user", "content": "Hello from FreeRouter!" }
]
}'Python, Node and every other SDK
The same base URL and key drop into the OpenAI Python and Node SDKs, the Anthropic SDKs, Claude Code, the Vercel AI SDK, LangChain and LiteLLM — one tab each, with a streaming variant, in Use your SDK.
Step 5 — Verify and tune
- Check the
X-FreeRouter-Providerresponse header — it names the gateway that served the request, so you can confirm your rule is doing what you expect. - List what's available to your key with
GET /v1/models. - Got an error instead? Troubleshooting covers every status with its fix — a 402 on the first call is almost always an unfunded gateway account.
- Watch volume, errors, and latency on the Usage & Spend page, then rebalance weights or reorder priorities on the Routing Rules page — changes apply to the next request, no redeploy.