OpenRouter¶

OpenRouter is a meta-provider that exposes 200+ AI models from every major lab (Anthropic, OpenAI, Google, Meta, Mistral, Qwen, DeepSeek, Cohere, and many more) behind a single API key. In Whittl it's the most flexible backend by a wide margin — you can switch between models mid-project, access free-tier variants with rate limits, and use niche models not otherwise available in Whittl.

This page covers setup, the Models dialog, capability chips, routing options, vision model specifics, and cost-saving patterns.

Setup¶

Go to openrouter.ai and create an account.
Add credit to your account — $5 minimum is fine for experimentation. You can top up anytime.
Navigate to Keys in the dashboard and create an API key. It starts with sk-or-v1-....
In Whittl, click the key button next to the backend dropdown in the chat panel.
Paste the key into the OpenRouter API Key field. Whittl validates it before saving.

Once validated, switch the backend dropdown to OpenRouter. The model indicator in the chat panel will show whichever model is currently selected (defaults to openrouter/auto on first use).

The Models dialog¶

Click the Models button next to the backend dropdown to open the Models dialog. This is the single most-used OpenRouter UI in Whittl.

What you see¶

Column	Meaning
Favorite star ()	Click to star. Starred models bubble to the top of the model dropdown.
Model name + ID	Human-readable name on top, full provider/model-id underneath
Capability chips	`[Tools]` `[Thinks]` `[Long]` `[Vision]` — which features the model supports
Context window	Max input tokens (128K, 1M, etc.)
Input / Output price	Per-million-token cost, OpenRouter's final price including their margin

The filter dropdown above the list narrows the view:

All — every model OpenRouter exposes
★ Favorites — only starred models
Supports Tools — models that handle tool-use (Whittl's modify path uses this)
Vision — vision-capable models (for screenshot-to-app)
Free — the free models OpenRouter offers right now (new in v2.6.0)
Long context (100K+) — context windows of 100K tokens or more
Cheap — budget tier
Premium — top-tier models regardless of provider

Sort order¶

Default sort: starred models → by capability count → alphabetical by name. This puts the best-value models you care about at the top consistently.

Capability chips explained¶

Four chips appear per model. Each is either filled (capability supported) or grayed out (not supported).

[Tools] — the model accepts OpenAI-format tool definitions and emits tool calls. Whittl's agent loop uses them to read, edit and run your project. A model without them still gets the loop: it writes short Python scripts that make the edits instead (code mode, see The Agent Loop).
[Thinks] — the model supports explicit reasoning / thinking mode (o1-style reasoning chains, Claude's extended thinking, DeepSeek R1 reasoning). Whittl exposes this through the Think toggle in the chat panel for applicable backends.
[Long] — context window is 100K+ tokens. For big projects or agent sessions with lots of history.
[Vision] — accepts image inputs. Required for the Screenshot to App feature.

Chips are populated from OpenRouter's own supported_parameters metadata, so they reflect what the model actually does, not a marketing claim.

Routing options¶

`openrouter/auto` (meta-model)¶

Selecting openrouter/auto as your model tells OpenRouter to pick the best available model automatically for each request. It balances:

Model quality
Current latency per provider
Your account's credit balance
The specific prompt shape

When to use it:

You're experimenting and don't want to pick a model for every request
Your task isn't particularly sensitive to model choice (small modifications, cleanup tasks)

When NOT to use it:

You need vision (auto sometimes picks non-vision models and drops the image silently)
You care about a specific cost ceiling (auto can route to premium models)
You're doing Agent Mode work (pick a specific tier-S model)

Specific model IDs¶

Most experienced Whittl users pick an explicit model. Common picks:

Use case	Model ID
Cheap coding, fast iteration	`qwen/qwen3.6-plus`
Best-quality budget option	`anthropic/claude-haiku-4.5`
Premium general-purpose	`anthropic/claude-sonnet-5`
Vision (budget)	`google/gemini-2.5-flash-lite`
Vision (premium)	`anthropic/claude-opus-5`
Agent Mode (tier-S)	`anthropic/claude-sonnet-5` or `google/gemini-3.1-pro-preview`

Model IDs move. The Models dialog reads OpenRouter's live catalog, so treat this table as a starting point and confirm the exact ID there.

Free-tier models¶

OpenRouter offers some models free of charge, with rate limits (see Rate limits and credits below). Their ids end in :free, and the set changes often: free models arrive and leave every few weeks, so this page does not list them. OpenRouter's model list shows the current ones; filter it by price. Whittl's Models dialog lists the same live set: choose Free in its filter.

A free model can be slow at busy times and can be withdrawn without notice. When its provider is overloaded, Whittl asks again a few times and then says so in the chat (v2.6.0); if one keeps failing, pick another.

:free suffix isn't optional

The free versions of models have an explicit :free suffix on their ID (e.g. qwen/qwen3-coder:free). The suffix-less version is the paid variant. Whittl's Models dialog marks free versions clearly, but if you type a model ID manually, double-check.

Mix free and paid

A common Whittl setup: star one free model for cheap iteration and one premium model for quality. Use the free one by default and switch for the hard problem you hit once an hour. That drops a monthly AI spend to a few dollars without giving up the ability to solve hard problems.

Vision-capable models¶

For Screenshot to App, you need a vision-capable model. OpenRouter's current vision-capable set (filter the Models dialog to Vision for the live list):

Model	Provider	Typical cost per screenshot generation
`google/gemini-2.5-flash-lite`	Google	~$0.01
`qwen/qwen-2-vl-7b-instruct`	Alibaba	~$0.02
`google/gemini-2.5-flash`	Google	~$0.02
`anthropic/claude-haiku-4.5`	Anthropic	~$0.05
`google/gemma-3-27b-it`	Google	~$0.05
`meta-llama/llama-3.2-90b-vision-instruct`	Meta	~$0.10
`mistralai/pixtral-large-2411`	Mistral	~$0.15
`anthropic/claude-sonnet-5`	Anthropic	~$0.40
`anthropic/claude-opus-5`	Anthropic	~$1.50

For most screenshot-to-app work, google/gemini-2.5-flash-lite is the cheapest option that works reliably. Jump to Claude Haiku or Sonnet when you need more design fidelity.

Provider pinning and prompt caches¶

New in v2.5.0. OpenRouter can serve the same model from several providers, and it load-balances between them. Prompt caches are per provider, so every switch used to be a cold miss: on a big project every round re-processed the whole context, replies took 20 to 35 seconds instead of a few, and the cost meter bounced between provider names.

Whittl now notes which provider served the last round and pins the next round to it, with fallback allowed so an outage self-heals in one round. The pin is per model, so switching models re-routes fresh instead of wasting a round. On a large project this is the difference between cached=0 and cached=280,000 on every round. Watch the cost meter: a steady provider name and a large cached count mean the pin is working.

Which provider serves the first request¶

New in v2.6.0. The same model on OpenRouter is not always the same model. A popular open model can have twenty or more providers, at prices several times apart, and some of them run it at reduced precision (four bits instead of eight) to cut their costs. That shows up first on exact syntax and strictly formatted tool calls, which is most of what Whittl asks for. Price is no guide: a reduced-precision provider can be the cheapest or charge the full rate.

Before a model's first request in a session, Whittl reads that model's provider list from OpenRouter and decides two things:

Which providers to ask for, in order. Up to four providers that state they run the model at 8-bit precision or better, report as healthy, and offer a context window of at least 200,000 tokens (enough for the largest prompt Whittl builds). Cheapest first; when two cost the same, the one with the better uptime goes first.
Which providers to refuse outright. Any provider that states it runs the model below 8-bit, and any whose context window is under 200,000 tokens. These are refused even if the preferred providers are down.

The first reply's provider then becomes the pin described above. A few details:

A provider that does not say what it runs is never preferred, but it is not refused either. Every provider for some models, Claude included, reports its precision as unknown. For those Whittl expresses no preference, and OpenRouter routes the way it always does.
Whittl never refuses every provider. If the refusals would leave nothing to route to, it refuses none: a request with nowhere to go fails, and a weaker answer is better than none.
A provider that returns broken tool calls is left out. If a provider sends back a tool call whose arguments cannot be read, Whittl leaves that provider out for that model for the rest of the session and stops pinning to it, so the model's next try goes elsewhere. Up to two providers per model, and never the last one.
The chat names the model that answered. When OpenRouter serves a different model from the one you picked (for example with openrouter/auto), the reply is labelled with the model that actually answered.

The provider list is read once per model per session. If it cannot be read, Whittl sends no preference and OpenRouter routes as usual.

Cost compared to direct providers¶

OpenRouter adds roughly 5–10% margin on top of each provider's direct pricing. So:

Claude via OpenRouter ≈ 5% more expensive than Claude API direct
Gemini via OpenRouter ≈ 5–10% more expensive than Gemini API direct
DeepSeek via OpenRouter ≈ 5% more expensive than DeepSeek API direct

In exchange you get a single consolidated bill, access to models you couldn't otherwise use, automatic fallback if a provider has an outage, and free models alongside paid ones.

Rule of thumb: if you exclusively use one provider, use their API directly. If you use two or more, OpenRouter's margin is outweighed by the flexibility.

Rate limits and credits¶

OpenRouter rate limits depend on your account credit balance:

No credit — severely rate-limited (~10 req/min across all free models)
$5+ credit — normal free-model rate limits (~20 req/min per model)
$10+ credit — elevated limits on paid models

Credits persist until used; no expiry. $5 typically lasts a month of casual Whittl usage on mid-tier models.

Troubleshooting¶

Model returns 'Deprecated' error

OpenRouter occasionally deprecates models when providers pull them. Whittl's update-checker surfaces the error with a pointer back to the Models dialog. Just pick a new model; your project state is unaffected.

Image silently ignored with vision model

Two causes:

You picked openrouter/auto and auto routed to a non-vision model. Switch to an explicit [Vision] model.
The model claims vision but doesn't handle it well. Small and free vision models are spottier than Claude or Gemini on complex UIs. Try a higher-tier model.

Favorites disappeared

This was a v2.2 bug where the update-checker racing with favorites writes would clobber them. Fixed in v2.3. If you're running v2.2 or earlier, upgrade.

Sudden cost spike in OpenRouter dashboard

If you recently switched Agent Mode on and a tier-S model ran a long loop, you can burn a lot of credit fast. With Agent Mode on, one message can run up to 50 rounds on a tier-S model and 20 on tier-A; with it off, 10 on every tier. Check Preferences > AI Generation > Agent Mode (experimental) is set the way you expect, and see Monitoring spend for where Whittl shows what each request cost.

What's next¶

Screenshot to App — vision-model workflow using OpenRouter
Agent Mode — which OpenRouter models qualify for which tier
Auto-fix Rules — how Whittl's local layer compensates for cheaper models' mistakes