Get an OpenRouter key

This is optional. Most exercises run on your Claude subscription through Claude Code or claude -p, and those never need a key. Exercises tagged API run code that calls a model directly (the Claude Agent SDK, the Anthropic or OpenAI SDK, or embeddings). OpenRouter is one way to run them: one key and one prepaid balance give you hundreds of models from Anthropic, OpenAI, Google, DeepSeek, Qwen and other open-weight labs, behind both an Anthropic-compatible and an OpenAI-compatible API. The other way is a free local model; see OpenRouter or a local model? to choose.

Before you start

• A personal email address or login for a new OpenRouter account.
• A payment method. OpenRouter accepts major credit cards, AliPay and USDC.
• Small budgets go a long way. Per million input tokens, anthropic/claude-haiku-5.5 costs $0.10, anthropic/claude-sonnet-5.5 $2 and deepseek/deepseek-v4-flash about $0.09. A typical exercise costs a few cents.

1. Create an account and buy credits

1. Sign up at openrouter.ai.
2. Open the Credits page and buy a small amount, such as $10.

Credits are a prepaid balance in US dollars, and each request's cost is deducted from it. OpenRouter passes model prices through at the provider's list price and charges a fee when you buy credits instead. Unused credits can be refunded only within 24 hours of purchase, and OpenRouter may expire them a year after purchase, so buy small amounts. Buying at least 10 credits also raises your free-model limit (step 5).

2. Create a key with a credit limit

1. Open the API keys page and create a key.
2. Name it (for example learning-laptop) and set a credit limit, such as $5. You can also make the limit reset daily, weekly or monthly.
3. Copy the key, which starts with sk-or-. If you lose it, delete it and create a new one.

Once a key has used its limit, requests with it are rejected until you raise the limit or it resets. A limit per key means a runaway agent loop costs you at most that amount. Check a key's remaining limit at any time:

curl -s https://openrouter.ai/api/v1/key -H "Authorization: Bearer $OPENROUTER_API_KEY"

3. Keep the key in the project's .env

Exercise answers read their configuration from a .env file in the project folder and load it only for the scripts that need it (node --env-file-if-exists=.env, uv run --env-file .env). Make sure git ignores it:

echo ".env" >> .gitignore
git check-ignore .env   # prints ".env" when it's ignored

Each answer ships a .env.example; copy it to .env and paste your key into the block you use (step 6 shows both). For a quick test in one terminal you can also run export OPENROUTER_API_KEY="sk-or-...", which the curl commands on this page use.

Never paste a key into a prompt, a commit, a screenshot or a shared notebook. OpenRouter is a GitHub secret-scanning partner and emails you if it finds a key exposed; delete it and create another.

4. Check the privacy settings

OpenRouter forwards each request to a provider (Anthropic, OpenAI, Google, or a host running an open-weight model). Two layers matter:

• OpenRouter itself doesn't store prompts or responses unless you opt in. Both opt-ins are off by default: Input & Output Logging in Observability settings (saves prompts so you can read them on your Logs page), and OpenRouter Use of Inputs/Outputs in Privacy settings (lets OpenRouter use your data for a 1% discount). It always stores metadata such as token counts and latency.
• Providers have their own policies. In your privacy settings you can stop routing to providers that may train on your data, and enforce Zero Data Retention (ZDR), which routes only to endpoints that don't store prompts. ZDR has a separate toggle per model group (Anthropic, OpenAI, Google, SpaceXAI, all other models); a request can also ask for it with "provider": {"zdr": true}.

Exercises use synthetic data only, so the defaults are fine. Turning on ZDR for all other models is a sensible extra step, and may make some models unavailable.

5. Know the free models and their limits

Some models have a free variant: append :free to a slug that lists one, such as google/gemma-4-31b-it:free. The model list filtered to free shows what's available today. They are rate-limited:

Free models are fine for quick experiments but too limited for an agent loop that makes dozens of calls. A negative balance blocks free models too, with HTTP 402.

6. Pick a model and connect your code

A model is named by a slug, author/model. Ones the answers use or suggest:

Aliases such as ~anthropic/claude-sonnet-latest always resolve to the newest model in a family. They're handy for trying things, but use a fixed slug for a run whose numbers go in a deliverable, so you can say which model produced them. The full catalogue is at openrouter.ai/models.

Exercise code connects in one of two ways, depending on the SDK.

Claude Agent SDK and Anthropic SDK code

OpenRouter serves the Anthropic Messages API at https://openrouter.ai/api. The SDKs read these variables themselves:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=sk-or-...
ANTHROPIC_API_KEY=
MODEL=anthropic/claude-sonnet-5.5

ANTHROPIC_AUTH_TOKEN is sent as a bearer token, which is how OpenRouter authenticates. ANTHROPIC_API_KEY must be explicitly empty, so nothing falls back to authenticating with Anthropic directly. MODEL can be any OpenRouter slug.

Everything else: the OpenAI SDK

Plain model calls, structured output and embeddings use the OpenAI SDK, which reads its own two variables:

OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_API_KEY=sk-or-...
MODEL=anthropic/claude-haiku-5.5
EMBEDDINGS_MODEL=openai/text-embedding-3-small

OpenRouter has an embeddings endpoint (/api/v1/embeddings) with models from OpenAI, Google, Qwen, Voyage and others. Both clients are created with no arguments; OpenRouter or a local model? shows the code.

Check it works

curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"anthropic/claude-haiku-5.5","max_tokens":20,"messages":[{"role":"user","content":"Reply with the single word: ready"}]}' \
  | jq -r '.choices[0].message.content'

Expected output:

ready

The request also appears on your Activity page with its cost.

Troubleshooting

HTTP 401. The key is missing, mistyped or deleted. Run echo "$OPENROUTER_API_KEY" | cut -c1-8 and check that it prints sk-or-. In a project, check that you passed --env-file and that the key is in ANTHROPIC_AUTH_TOKEN (Agent SDK) or OPENAI_API_KEY (OpenAI SDK), not only in OPENROUTER_API_KEY.

HTTP 402. Your balance can't cover the request: add credits on the Credits page. A negative balance gives 402 even on :free models. If the error's limit_source names the key limit, raise the key's credit limit or wait for it to reset.

The model isn't found. The slug is misspelled, or it's a native Anthropic ID such as claude-sonnet-5-5. OpenRouter slugs include the author and use dots: anthropic/claude-sonnet-5.5. If MODEL names an Ollama model, your base URL still points at OpenRouter, or the other way round.

claude -p suddenly spends OpenRouter credits. The ANTHROPIC_* variables were exported in your shell. Run /status in Claude Code: if it shows https://openrouter.ai/api as the base URL, run unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY, remove them from your shell profile, and keep them in .env only.

Going further

• OpenRouter or a local model?, the configuration pattern every answer uses
• Local models with Ollama, the free alternative