OpenRouter setup: API key, free models and pricing
Quick answer: OpenRouter is one API in front of hundreds of models from many providers. Create an account, add credits if you need paid models, and create an API key at openrouter.ai/settings/keys. Then point any OpenAI-compatible tool at https://openrouter.ai/api/v1 with that key. Free models end in :free and are capped at 50 requests a day, or 1,000 a day once you have bought at least 10 credits. Paid models cost the provider’s listed price; OpenRouter charges a 5.5% fee when you buy credits.
This guide takes you from a new account to one checked request, then covers the free tier, what you actually pay, connecting Claude Code, and the errors I have hit in my own videos.
I use OpenRouter as a backup provider in several agents. In How To Build Apps Using Free Claude Code! I add an OpenRouter key to a community proxy and build a Next.js app on free models. In The Terminal AI Coding Agent You Need to Try I run out of credits mid-task, and in Hermes Agent Is Better Than OpenClaw I hit an authentication error. Limits, fees and setup steps below come from OpenRouter’s own documentation, checked November 1, 2026.
Create an OpenRouter API key
- Sign up at openrouter.ai.
- If you plan to use paid models, open the Credits page and add credits. Credits are a prepaid balance in US dollars that each request draws from. You can skip this step for free models.
- Open Settings › Keys (
openrouter.ai/settings/keys) and create a key. Name it after the tool that will use it, such as “hermes” or “claude-code”. - Optionally set a credit limit on the key, so one tool cannot spend your whole balance.
- Copy the key into that tool’s settings or an environment variable. Do not paste it into a chat, a screenshot or a file you commit.
One key per tool makes problems easier to trace, because the Activity page can filter usage by key. Extra keys or accounts do not raise your rate limits: OpenRouter applies them globally to your account.
Make a first request and check the key
OpenRouter follows the OpenAI API format for /chat/completions, /responses and /completions, so any OpenAI SDK works by changing the base URL. A minimal test with the free model router:
export OPENROUTER_API_KEY="your-key-here"
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "openrouter/free", "messages": [{"role": "user", "content": "Reply with the word ready."}]}'openrouter/free picks one of the free models for you. To pin a model, use its ID from the models page, such as a model ending in :free. Check the reply, then find the request on the Activity page before you connect a bigger tool.
To see what a key has left, call the key endpoint:
curl https://openrouter.ai/api/v1/key \
-H "Authorization: Bearer $OPENROUTER_API_KEY"The response includes the key’s credit limit and limit_remaining, usage today, this week and this month, and free_model_daily_requests with the free requests used and remaining today. If API requests are new to you, the first API request guide walks through keys, headers and errors with a free local example.
OpenRouter free models and their limits
Free model variants have IDs ending in :free. They have their own limits, separate from paid models:
| Credits bought (all time) | Requests per minute | Requests per day |
|---|---|---|
| Less than 10 | 20 | 50 |
| At least 10 | 20 | 1,000 |
The daily count resets at midnight UTC. Buying 10 credits once raises the cap for good, even if you never spend them on paid models. OpenRouter describes free models as usually not suitable for production. New users also get a small free allowance to test the service.
Two things trip people up:
- A negative balance blocks free models too. If your balance goes below zero, requests can fail with
402, including requests to free models, until you add credits. - Free means the provider may be busy. A free model can return
429because the upstream provider is at capacity, not because you hit your own cap.
In the Free Claude Code video, a free model built the first version of a Next.js app while my balance stayed at $1.68. In the Pi video, my balance had gone negative, so I switched to a free model instead of topping up. When I tried Gemma 4 through OpenRouter, it answered in the wrong language; I may have picked the wrong variant. Either way, that is a model choice problem, not an account problem. Test a free model on a small task before you trust it with a long one.
OpenRouter pricing: what you actually pay
- Model usage: each model page lists a price per million input and output tokens, and some models also charge per request, per image or for reasoning tokens. OpenRouter passes the provider’s price through with no markup.
- Credit purchases: a 5.5% fee with a $0.80 minimum on card payments, or 5% for crypto. Fees are not refundable.
- Your own provider keys (BYOK): pay-as-you-go accounts get $25,000 a month of BYOK usage, measured at list price, with no fee. Above that, the fee is 5% of what the same request would normally cost on OpenRouter.
- Refunds and expiry: unused credits can be refunded within 24 hours of purchase. OpenRouter reserves the right to expire unused credits a year after purchase.
So OpenRouter costs a little more than going direct when you buy credits, in exchange for one key, one bill and automatic fallback between providers. If you only ever use one provider’s models, its own API is usually cheaper. If you use an agent with a flat monthly plan instead, compare OpenCode Go, which trades per-request billing for monthly limits.
By default, OpenRouter does not log your prompts or completions. You can opt in to logging for a 1% discount, and providers that log or train on data are skipped unless you allow them in privacy settings.
Use OpenRouter with Claude Code
Claude Code can talk to OpenRouter directly, with no proxy. OpenRouter’s guide sets three environment variables:
export OPENROUTER_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""- Add these to your shell profile, then open a new terminal so they take effect.
ANTHROPIC_API_KEYmust be an empty string, or Claude Code may sign in to Anthropic directly instead. - If you were signed in to Claude Code with an Anthropic account, run
/logoutonce, then quit and restartclaude. - Run
/status. It should showANTHROPIC_AUTH_TOKENas the auth token andhttps://openrouter.ai/apias the base URL. - Send a short prompt and check that it appears on the Activity page.
OpenRouter only guarantees this setup with Anthropic as the provider, and Claude Code is built for Anthropic models. Routing Claude Code to other models through OpenRouter may not work correctly. If you are new to Claude Code, start with the Claude Code beginner guide, then switch providers once a normal session works.
The “Free Claude Code” in my video is a different thing: a community proxy on GitHub that sends Claude Code requests to free models from NVIDIA NIM, OpenRouter and others. It is not an Anthropic or OpenRouter product, so read its code and settings before giving it a key.
Use OpenRouter in Hermes, OpenCode, Kilo Code and other agents
Most coding agents list OpenRouter as a built-in provider, so you paste the key rather than set a base URL:
- Hermes Agent: turn on OpenRouter in the setup wizard, paste the key, then pick a model with
/model. The Hermes Desktop guide covers the install. - OpenCode: OpenRouter is one of its documented providers. See the OpenCode vs Claude Code guide for setup.
- Kilo Code: its authentication page lists OpenRouter as a provider. Add the key under Settings › Providers. See the Kilo Code tutorial.
- A local gateway: tools such as 9Router can sit in front of OpenRouter and other providers. See the 9Router setup guide.
Whichever tool you use, send one short prompt and confirm it on the Activity page before starting real work. A model list loading in the tool only proves the key was accepted, not that generation works.
OpenRouter errors: 401, 402, 403 and 429
| Code | What it means | What to do |
|---|---|---|
| 401 | The request was not authenticated | Check the key was pasted whole, has not been deleted, and is the one the tool is actually sending |
| 402 | Not enough credit: your balance, the key’s own limit, or too many paid requests in flight | Read error.metadata.limit_source; add credits, raise the key’s limit, wait for the Retry-After time, or lower max_tokens |
| 403 | A budget set by an organization admin is spent | Wait for the reset time in the error, or ask the admin to raise it |
| 429 | Rate limited, by your free-model cap or by a busy provider | Retry with backoff, buy 10 credits to raise the free cap, use the paid version, or add a fallback model |
In the Hermes video, my requests failed with “HTTP 401: User not found” even though the account still had 39 cents of credit. Credit was unlikely to be the cause. A 401 points at the key or account the tool is sending, so I checked the model on OpenRouter and reran Hermes setup. Start there: create a fresh key, paste it once, and test it with the curl request above before blaming the agent.
If a long task fails partway, call /api/v1/key before retrying. It tells you whether you ran out of credit, hit a key limit or used up the day’s free requests.
FAQ
How do I get an OpenRouter API key?
Sign up at openrouter.ai, open Settings › Keys and create a key. Add credits on the Credits page if you want paid models; free models work without a purchase, within their daily caps.
Is OpenRouter free?
Signing up is free, and models ending in :free cost nothing. They are limited to 20 requests a minute and 50 a day, or 1,000 a day after you have bought at least 10 credits. Paid models draw from your credit balance.
How much does OpenRouter charge?
Model usage is billed at the provider’s listed price with no markup. Buying credits carries a 5.5% fee with a $0.80 minimum, or 5% for crypto. Using your own provider keys is free up to $25,000 a month of usage, then 5%.
Why do I get a 402 error on a free model?
A negative credit balance can block requests to free models too. Add credits to bring the balance above zero. The error’s limit_source field tells you whether the balance, a key limit or in-flight requests caused it.
Can I use OpenRouter with Claude Code?
Yes. Set ANTHROPIC_BASE_URL to https://openrouter.ai/api, put your OpenRouter key in ANTHROPIC_AUTH_TOKEN and set ANTHROPIC_API_KEY to an empty string. OpenRouter only guarantees this with Anthropic as the provider.
Do more API keys raise my rate limit?
No. OpenRouter applies limits to your account as a whole. Separate keys help you track and cap spending per tool, not get more requests.
Sources
- OpenRouter FAQ: fees, BYOK, free tier, refunds and privacy
- OpenRouter: credit limits, budgets and rate limits
- OpenRouter: Claude Code integration
- Kilo Code: provider authentication, including OpenRouter
Build the next one with AI Income Lab
Step-by-step courses, reusable templates, and a community that answers when you get stuck.
- Courses for builds like this one
- Copy-ready templates
- Ask questions while you build
- Weekly coaching on VIP
