How to Use OpenRouter: The Beginner's Guide (One Key, Every Model, Fallback Routing, and the Free-Model Bench)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 16 min read

How to Use OpenRouter: The Beginner's Guide (One Key, Every Model, Fallback Routing, and the Free-Model Bench)

Learning how to use OpenRouter is the fastest way to stop juggling AI provider accounts. If you have ever wanted to compare Claude, GPT, Gemini, and Llama side by side in the same afternoon — without opening four accounts, storing four API keys, and reading four sets of docs — OpenRouter is the shortcut: one account, one API key, one OpenAI-compatible endpoint, and a catalog of 400+ models behind it. This OpenRouter tutorial for beginners walks the complete arc in one sitting: create your account, create a properly limited API key, make your first call, swap models by changing a single string, read the model catalog like a buyer, test everything on the free-model bench, add fallback routing so one provider outage never breaks your app, and set the cost controls that keep a side project from surprising you. If you would rather click than curl for your first test, run the call through the Hoppscotch API Studio — paste the endpoint, add your key as a Bearer token, and watch the JSON come back before you write a line of code.

How Do I Use OpenRouter?

You use OpenRouter by creating an account, generating an API key with a credit limit, and sending OpenAI-shaped requests to https://openrouter.ai/api/v1 with the model you want named in the body. The whole beginner loop fits in under an hour, and most of it is familiar if you have ever called any REST API. Treat this list as your OpenRouter for beginners checklist:

1. Create your account — sign up at openrouter.ai; no credit card is required to start.
2. Create an API key — open openrouter.ai/keys, give the key a name, and set a credit limit on it before it ever makes a call.
3. Store the key as an environment variable — OPENROUTER_API_KEY in a .env file that is gitignored, never in your code or a frontend bundle.
4. Make your first call — POST a chat-completions request to https://openrouter.ai/api/v1/chat/completions with an Authorization: Bearer header.
5. Swap models with one string — change the model field from one provider/model ID to another; nothing else in your code changes.
6. Test for free — use :free model variants and the on-site playground before you spend a cent.
7. Add fallback routing — pass a models array ordered by preference; if one model errors, the gateway automatically tries the next.
8. Cap your spend — per-key credit limits plus the usage dashboard are your budget controls; set them on day one.

What Is OpenRouter, Exactly?

OpenRouter is a unified inference gateway, not a model. You send a standard chat-completions request to one endpoint, and OpenRouter forwards it to whichever underlying provider you selected — Anthropic, OpenAI, Google, Meta, Mistral, DeepSeek, Qwen, and dozens of others — then returns the response in the same shape you would get from OpenAI directly. It handles provider authentication, retries, streaming, and a single invoice, and it normalizes pricing so you can compare cost per million tokens across vendors. What it is not: a model you train, a fine-tuning platform, a vector store, or a host for weights. It is plumbing — one key and one base URL where there used to be nine logins. The official quickstart, updated October 16, 2026, lists three integration paths: the raw API for full control in any language, the official client SDKs for type-safe calls, and an agent SDK for tool-using agents — plus a drop-in route where you point the OpenAI SDK at OpenRouter's base URL and change nothing else.

How Do I Create an OpenRouter API Key?

You create your key at openrouter.ai/keys: give it a name and choose a credit limit, or leave it unlimited. This is the step most beginners rush, and it is the one that protects your wallet — once a key has used its credit limit, requests with it are rejected until you raise the limit on the key's page (daily, weekly, and monthly limits reset on their own schedule instead). Keys created for you during onboarding arrive with a $100 credit limit and expire after 180 days, per the official authentication docs updated September 18, 2026. Copy the key exactly once, put it in OPENROUTER_API_KEY, and never commit it: OpenRouter is a GitHub secret-scanning partner, so a key pushed to a public repo will trigger an email warning to you — but by then someone may already have spent your balance. Our GitHub beginner guide covers the .gitignore habit that keeps secrets out of commits; add .env to it before you paste anything sensitive. Create separate keys for local development, staging, and production, so one leak never takes down everything.

OPENROUTER_API_KEY=your-key-here

How Do I Make My First OpenRouter API Call?

You make your first call with a single curl to the chat-completions endpoint — the fastest way to prove your key, your headers, and your model ID are all correct before you write application code. Set the Authorization header to a Bearer token with your key, and add the two optional headers OpenRouter uses for app attribution: HTTP-Referer with your site URL and X-Title with your app name. They are not required for the call to work, but they unlock better analytics and let your app appear on OpenRouter's public leaderboards:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://your-site.com" \
  -H "X-Title: My First App" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Explain what an API gateway does in one sentence."}]
  }'

The response is standard OpenAI-shaped JSON — choices[0].message.content holds the answer. If the JSON looks like a wall of braces, paste it into a JSON viewer to read the structure: the usage object tells you exactly how many prompt and completion tokens the call consumed, which is how you will later reconcile spend. Model IDs change as providers release new versions, so treat any ID you see in a tutorial — including this one — as a starting point and confirm the current ID on openrouter.ai/models before you ship.

How Do I Swap Models Without Rewriting My Code?

You swap models by changing exactly one string: the model field. Because every provider sits behind the same OpenAI-compatible interface, your request shape, your parsing code, and your error handling stay identical whether you are calling Anthropic, Google, or Meta. The model ID format is always provider/model, for example anthropic/claude-sonnet-4.5 or google/gemini-2.5-pro. If you already have code written against the OpenAI SDK, the swap is even smaller — point the client at OpenRouter's base URL and keep everything else:

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",  # the only line that changes
    api_key=os.environ["OPENROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",  # swap this string to change models
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

This one-string swap is the whole reason the gateway exists. Want to A/B test two models on the same prompt? Change the string. A provider has an outage? Change the string. A cheaper model just launched and you want to try it on real traffic? Change the string — then make that decision permanent with fallback routing, covered below.

How Do I Read the OpenRouter Model Catalog?

You read the catalog at openrouter.ai/models as a buyer, not a browser. Every model row shows its provider/model ID, its context window, and its per-token price, and the list can be sorted cheapest-first so you can see what a million tokens actually costs before you commit to an architecture. Two details matter most for beginners. First, the :free suffix marks a free catalog variant of a model — a separate entry you request exactly like a paid one, but billed at zero with its own rate limits. Second, each model lists its supported parameters (tool calling, structured outputs, reasoning, and the rest), so you can check that the model you picked actually supports the features your code relies on. The catalog is also available as a free public API, which means you can pull the live list — IDs, prices, context lengths — into your own tooling instead of hardcoding model names that will go stale.

Which OpenRouter Models Are Free?

The OpenRouter free models are the :free variants in the catalog — real models served at zero cost with tighter rate limits, made for testing and learning rather than production traffic. To use them, search the models page for :free, copy the ID exactly as shown, and call it like any other model; the request counts against the free tier's daily request quota instead of your credit balance. Checked today, October 30, 2026, the free bench holds 15 variants — including nvidia/nemotron-3-ultra-550b-a55b:free, thinkingmachines/inkling:free, and cohere/north-mini-code:free — at 50 requests per day by default, rising to 1,000 a day once you have bought at least 10 credits, per the official FAQ. That is generous for an afternoon of experiments and gone by mid-afternoon if you point a loop at it, so plan heavy testing for the morning. Treat the list as a snapshot, not a promise: free-model availability rotates as providers change their terms — two entries are already marked "going away" this week — which is exactly why the rule for this lane is to read the current free list on openrouter.ai/models at the moment you build, never to copy a :free ID from a tutorial. The on-site playground is the zero-setup way to try the same free models in a chat interface before you touch code.

How Does OpenRouter Fallback Routing Work?

Fallback routing means you send a list of models instead of one, and OpenRouter walks the list until one answers. You pass a models array ordered by preference — no extra flag needed — and if your first choice returns an error, the gateway automatically retries the same request against the next model in the array. Per the current routing docs, any error can trigger a fallback: rate limits, downtime, capacity, context-length validation errors, or moderation flags on filtered models. This is the production answer to the demo-night problem of a provider outage:

{
  "models": [
    "anthropic/claude-sonnet-4.5",
    "openai/gpt-5-mini",
    "google/gemini-2.5-pro"
  ],
  "messages": [{"role": "user", "content": "Hello!"}]
}

Order the array the way you would order your own preferences: your best model first, your cheapest acceptable backup last. Billing follows the model that actually answers — if a free model fails over to a paid one, you pay the paid model's price. Note what fallback does not do — it does not pick the cheapest model for you, and it does not merge responses. It is a reliability ladder, not a cost optimizer. For cost, you pick the model deliberately from the catalog; for reliability, you give the gateway somewhere to go when your pick fails. If you build terminal-based AI agents, this same single key slots behind their model pickers — our OpenCode beginner guide walks the agent side, and OpenRouter is the key that lets those agents swap models without swapping credentials.

OpenRouter vs Direct Provider APIs: What Is the Honest Trade-Off?

Going through a gateway is a trade, and you should make it with your eyes open. Here is how the two routes compare on the dimensions beginners actually feel:

Two rows deserve emphasis. On price: third-party guides describe OpenRouter as passing through upstream provider rates without per-token markup, with the platform's cut taken as a fee when you buy credits — a September 2026 guide measured that fee at 5.5% on a $10 purchase. On privacy: your prompts do pass through OpenRouter's systems, so this is not the route for data you cannot share with a third party; zero-retention routing exists for stricter needs, but that is an advanced configuration, not a beginner default. Keep keys server-side always — if your app needs a backend to hold the key, our what is VPS hosting guide explains the server you would put it on. Never put an OpenRouter key in browser JavaScript or a mobile app: anyone can extract it and spend your balance.

How Does OpenRouter Pricing Work?

OpenRouter pricing is pay-as-you-go: every model has its own per-token price listed on the models page, and each call deducts the tokens it used from your credit balance. You fund the balance by buying credits — there is no minimum purchase and no lock-in on the Standard and Business plans, per the official pricing page checked today — and the usage dashboard shows spend per key, per model, and per day, so you can see exactly where the money went. The platform's cut is a fee on credit purchases, never on individual requests: 5.5% on Standard (with a $0.80 minimum fee; crypto payments 5%), 8% on Business — while inference itself is billed at each provider's list price with zero per-token markup, confirmed in the docs FAQ. Your cost controls are threefold: buy only what you need, set a credit limit on every key before its first call (a key at its limit gets its requests rejected instead of spending more), and do your experimenting on :free variants. A realistic beginner budget is a single small credit purchase plus free-tier testing — enough to build and demo, with the per-key limit as the guardrail that turns "I wonder what this costs" from a risk into a number.

Beginner Mistakes That Cost Money

Every one of these has burned a real beginner. Learn them here instead of in your billing dashboard:

Frequently Asked Questions

Is OpenRouter free?

Testing is free: the :free model variants cost nothing but share a daily request quota — 50 requests a day by default, 1,000 a day once you have bought at least 10 credits, per the official FAQ — and signup needs no credit card. Paid models are pay-as-you-go from a credit balance you top up with no minimum purchase. Think of it as free to learn, cheap to build, metered to scale.

Do I need a credit card to start with OpenRouter?

No. You can sign up, create a key, and make calls against the free-model tier without adding a payment method. You only pay when you buy credits for paid models — and onboarding keys arrive with their own $100 credit limit and a 180-day expiry, so even the paid side starts fenced in.

Can I use OpenRouter with the OpenAI SDK I already know?

Yes — that is the headline feature. Point the OpenAI Python or Node client at https://openrouter.ai/api/v1, drop your OpenRouter key into the key field, and your existing code works unchanged. There are also official OpenRouter SDKs (npm install @openrouter/sdk, pip install openrouter) if you want types generated from their API spec.

What happens when my API key hits its credit limit?

Requests with that key are rejected until you raise the limit on the key's page — or until a daily, weekly, or monthly limit resets on its own. Nothing is charged beyond the limit, which is exactly why you set one before the first paid call rather than after the first surprise bill.

Is my prompt data private on OpenRouter?

Your prompts pass through OpenRouter's infrastructure on the way to the provider, so treat the gateway as a party to your data flow. Do not send anything you could not share with a third party, keep keys server-side, and look into zero-retention routing only once you outgrow the beginner setup — it is an advanced option, not a default promise.

Sources

• OpenRouter quickstart docs (three integration paths — API, client SDKs, agent SDK; OpenAI SDK drop-in; MCP server for AI assistants) — https://openrouter.ai/docs — updated October 16, 2026, crawled October 30, 2026
• OpenRouter API authentication docs (key creation with name + credit limit, requests rejected at limit, onboarding keys $100 limit expiring after 180 days, Bearer auth, GitHub secret-scanning partnership) — https://openrouter.ai/docs/api-reference/authentication — updated September 18, 2026, crawled October 30, 2026
• OpenRouter models docs (400+ models, :free catalog variant suffix, provider/model ID format, public Models API) — https://openrouter.ai/docs/models — updated October 30, 2026, crawled October 30, 2026
• Ahmad Rosid's OpenRouter guide (SDK + fetch examples, fallback via models array, official SDK install commands) — https://ahmadrosid.com/blog/how-to-use-openrouter — updated October 20, 2026, crawled October 30, 2026
• OpenRouter model-fallbacks docs (fallback via models array with no route flag — legacy route: "fallback" removed; any error can trigger a fallback; billing follows the model that answers) — https://openrouter.ai/docs/guides/routing/model-fallbacks — read October 30, 2026
• OpenRouter pricing page (no minimums or lock-in on Standard/Business; 5.5% Standard credit-purchase fee with $0.80 minimum, 5% crypto, 8% Business; inference billed at provider list price, zero per-token markup) — https://openrouter.ai/pricing — read October 30, 2026
• OpenRouter docs FAQ (free-model rate limits: 50 requests/day default, 1,000/day after buying at least 10 credits) — https://openrouter.ai/docs/faq — read October 30, 2026
• OpenRouter models page (:free list checked today — 15 variants including nvidia/nemotron-3-ultra-550b-a55b:free, thinkingmachines/inkling:free, cohere/north-mini-code:free; two entries marked going away this week) — https://openrouter.ai/models — read October 30, 2026
• ampm-aiops OpenRouter free-tier guide (25+ free models, 50 requests/day quota resetting at UTC midnight, $10 deposit with 5.5% platform fee) — https://ampm-aiops.com — written and price-verified September 22, 2026, via search October 30, 2026
• Enterprise DNA OpenRouter API tutorial (unified gateway concept, single invoice, per-key separation across environments, never expose keys in browser JS) — https://enterprisedna.co — updated September 28, 2026, via search October 30, 2026
• DataCamp OpenRouter guide (400+ models, one key, per-token price comparison across vendors) and AIPure OpenRouter guide (upstream provider rates passed through without per-token markup) — via search October 30, 2026