OpenRouter Gateway¶
OpenRouter is the preferred single-key gateway for Primr research. When configured,
it serves as the default provider route across utility, writing, and reasoning roles.
On the current static token plan the default full report plus AI Strategy
dry run is about $0.68. The same route was about $0.67 on 2026-10-28, and
about $1.07 on 2026-10-12. The estimate does not assume prompt-cache savings,
and it does not include OpenRouter credit-purchase fees. The live
primr --dry-run output is authoritative.
Configuring OPENROUTER_API_KEY activates OpenRouter routing by default, while
preserving Primr's mandatory dry-run estimate and explicit spend approval gates.
Configure the key¶
Use Primr's hidden prompt so the secret does not enter shell history:
primr keys test openrouter performs an authenticated request to OpenRouter's
current-key endpoint.
It does not generate text or consume model tokens. The public model catalog is
not used as an authentication test because it also returns successfully for
invalid credentials. primr keys path prints the active user config file.
Typical locations are %APPDATA%\primr\.env on Windows and
~/.config/primr/.env on Linux. A project-local .env can override the user
file, but the user file is preferable for a reusable personal key.
The underlying variable is:
Do not commit either .env file.
For defense in depth, use a dedicated OpenRouter key with an account-side spending limit no higher than you are willing to authorize independently of Primr. Primr's per-run approval and budget checks remain the primary gate.
Provider selection and opt-out¶
Because OpenRouter routes by default when OPENROUTER_API_KEY is present, no
secondary flag is required for standard runs.
To override OpenRouter and explicitly route through direct providers (e.g. Gemini or xAI), set:
To disable OpenRouter routing entirely without deleting your key:
Then inspect the exact plan before any billable run:
The dry run remains network-free and makes no model calls. Normal terminal
execution still asks for confirmation. Automation may use --skip-confirm
only after a person has reviewed and approved that fresh quote. MCP and A2A
use the same estimate-bound approval and cost-cap contract.
Set a per-run ceiling¶
--budget is a maximum for one Primr run. It is not a spending target and does
not approve the run. For example:
The human preview shows the $10 ceiling, the estimate, and whether the plan is within the ceiling. The JSON preview exposes the same decision:
{
"provider_ready": true,
"execution_ready": true,
"budget_enforcement": {
"ceiling_usd": 10.0,
"estimated_cost_usd": 1.07,
"within_budget": true
}
}
The shown cost is the 2026-10-12 two-decimal dry-run display. A live JSON
preview reports the unrounded estimator total. The live dry run is authoritative. If the
estimate exceeds the ceiling, execution_ready and within_budget are false,
and launch refuses before model calls. A valid ceiling is a finite positive
number.
Primr rechecks the same estimate when execution begins and activates runtime accounting at the supplied ceiling. Fast Standard runs checkpoint before optional spend stages. A model request that has already started cannot be stopped at an exact token boundary, so use a conservative ceiling and also put an independent spending limit on the dedicated OpenRouter key. OpenRouter key or organization limits reset according to their OpenRouter configuration and are separate from Primr's per-run ceiling.
After reviewing the fresh estimate, launch in a foreground terminal by removing
--dry-run; Primr will still ask for confirmation. Approved noninteractive
automation may also add --skip-confirm. Never treat the key, the routing
opt-in, the ceiling, or an earlier quote as approval by itself.
Curated model catalog and default recipe¶
The default OpenRouter route uses a balanced role recipe:
| Role | Default model | Input / output per 1M tokens |
|---|---|---|
| Utility | google/gemini-3.5-flash-lite |
$0.30 / $2.50 |
| Writing | openai/gpt-6-luna |
$0.10 / $0.50 ($0.20 / $0.75 above 272K) |
| Reasoning | deepseek/deepseek-v4.1-flash-1017 |
$0.30 / $1.20 (highest scheduled rate) |
The default full report plus AI Strategy dry run is about $0.68 on the
current static plan. It was about $0.67 on 2026-10-28, down from about
$1.07 with the previous GPT-4.1 Mini and DeepSeek V3.2 recipe. Prompt-cache savings are not
assumed, and OpenRouter credit-purchase fees are not included. The command's
live dry-run is authoritative because selected features, token plans, pricing,
and historical floors can change.
Expanded curated catalog¶
Primr supports an expanded set of pre-priced, verified models through OpenRouter:
| Provider / Family | Model identifier | Input / output per 1M tokens | Role suitability |
|---|---|---|---|
google/gemini-3.8-flash |
$0.75 / $3.75 |
Writing, Reasoning | |
google/gemini-3.7-flash |
$0.75 / $3.75 |
Unavailable for new selections; use google/gemini-3.8-flash |
|
google/gemini-3.5-flash-lite |
$0.30 / $2.50 |
Default utility | |
google/gemini-3.1-flash-lite |
$0.25 / $1.50 |
Unavailable for new selections; use google/gemini-3.5-flash-lite |
|
google/gemini-2.5-flash-lite |
$0.10 / $0.40 |
Unavailable for new selections; use google/gemini-3.5-flash-lite. The row stays for historical quotes. |
|
| OpenAI | openai/gpt-5.4-mini |
$0.75 / $4.50 |
Unavailable for new selections; use openai/gpt-6.1-terra |
| OpenAI | openai/gpt-5.4-nano |
$0.20 / $1.25 |
Unavailable for new selections; use openai/gpt-6-luna |
| OpenAI | openai/gpt-6.1-terra |
$1.00 / $5.00 |
Reasoning |
| OpenAI | openai/gpt-6-luna |
$0.10 / $0.50 |
Default writing |
| OpenAI | openai/gpt-4.1-mini |
$0.40 / $1.60 |
Unavailable; OpenAI shuts it down 2027-01-14 (use openai/gpt-6-luna) |
| Anthropic | anthropic/claude-sonnet-4.6 |
$3.00 / $15.00 |
Unavailable for new selections; use anthropic/claude-sonnet-5.5 |
| Anthropic | anthropic/claude-haiku-4.5 |
$1.00 / $5.00 |
Unavailable for new selections; use anthropic/claude-haiku-5.5 |
| DeepSeek | deepseek/deepseek-v3.2 |
$0.269 / $0.40 |
Reasoning |
| DeepSeek | deepseek/deepseek-chat |
$0.27 / $0.40 |
Reasoning, Writing |
| DeepSeek | deepseek/deepseek-r1 |
$0.55 / $2.19 |
Reasoning |
| Meta | meta-llama/llama-3.3-70b-instruct |
$0.12 / $0.30 |
Utility |
Granular role overrides¶
The October 13, 2026 OpenRouter catalog
listed an October 20 expiration for Gemini 2.5 Flash-Lite, Flash, Pro, and
the Flash/Pro batch slugs. The live base slugs no longer advertise that
date. Primr still expires google/gemini-2.5-flash:batch and
google/gemini-2.5-pro:batch on 2026-10-20. The registered
google/gemini-2.5-flash-lite row is unavailable for new selections and
names google/gemini-3.5-flash-lite. Historical pricing and catalog indices
stay. Select a replacement explicitly and obtain a new estimate; Primr does
not silently substitute one. The current utility default is
google/gemini-3.5-flash-lite at $0.30 / $2.50 per million input/output
tokens.
That gateway date is separate from the direct Gemini Developer API. The
deprecations page,
checked on 2026-11-16, shuts gemini-2.5-pro and gemini-2.5-flash down on
2026-12-01 and limits those two ids to users who have already used them. On
that date the provider routes Pro to gemini-3.8-flash and Flash to
gemini-3.5-flash-lite. Direct gemini-2.5-flash-lite is not deprecated
and remains available. Primr's
direct Gemini overrides use AI_FAST_MODEL, AI_REASONING_MODEL, and the
role-specific PRIMR_GEMINI_UTILITY_MODEL, PRIMR_GEMINI_WRITING_MODEL, and
PRIMR_GEMINI_REASONING_MODEL. When the selected provider is Gemini, its
role-specific override takes precedence: utility then falls back to
AI_FAST_MODEL, reasoning to AI_REASONING_MODEL, and writing to its
registered default. Provider and evaluation-recipe priorities are unchanged.
OpenRouter extensions cannot replace model or add fallback models through
extra_body; the selected model must match the retirement and pricing checks.
The developer pilot judge also uses
AI_REASONING_MODEL, defaulting to the registered Pro model. Running that
judge remains a paid evaluation requiring its own estimate and approval.
You can configure specific models for individual pipeline roles without modifying code:
PRIMR_OPENROUTER_UTILITY_MODEL=google/gemini-3.1-flash-lite
PRIMR_OPENROUTER_WRITING_MODEL=google/gemini-3.8-flash
PRIMR_OPENROUTER_REASONING_MODEL=anthropic/claude-sonnet-4.6
All selected models must exist in Primr's catalog or be registered with explicit pricing.
Request safeguards¶
Every OpenRouter generation request:
- applies the registered input and output rates as OpenRouter
max_priceceilings; - requires routed providers to support requested parameters by default;
- sets provider data collection to
deny; - requests zero-data-retention endpoints by default;
- records OpenRouter's response-level
usage.costas exact spend when present; - caps the requested output at the selected model's live catalog limit;
- identifies the application as
Primrthrough OpenRouter's optional app attribution headers; and - retains conservative token-based accounting when exact cost is absent or invalid.
These controls use OpenRouter's documented provider routing, zero-data retention, and usage accounting fields. Price ceilings limit rates, while Primr's estimate and approved budget limit the planned run shape.
Privacy and parameter tuning¶
Some models may have no provider that satisfies both price and privacy policies simultaneously, or may reject non-standard parameters:
- To allow non-ZDR providers explicitly while still denying providers that
collect data, set
PRIMR_OPENROUTER_ZDR=0. Review that privacy tradeoff before doing so. - For models that ignore optional parameters (such as custom temperature on
certain reasoning endpoints), set
PRIMR_OPENROUTER_REQUIRE_PARAMS=0to prevent OpenRouter from dropping eligible endpoints.
Custom OpenRouter model¶
An advanced user can select another OpenRouter model only with explicit, finite, nonnegative prices in USD per one million tokens:
PRIMR_OPENROUTER_MODEL=vendor/model-slug
PRIMR_OPENROUTER_INPUT_PRICE=0.25
PRIMR_OPENROUTER_OUTPUT_PRICE=0.75
PRIMR_OPENROUTER_MAX_INPUT_TOKENS=128000
PRIMR_OPENROUTER_MAX_OUTPUT_TOKENS=16384
The input and output prices become both the cost-estimator rates and the request's provider price ceilings. Missing, invalid, infinite, or negative prices make the model unavailable before any provider request.
Current boundaries¶
- OpenRouter is available to the Standard routed pipeline, including CLI, MCP, and A2A execution.
--grok-tier maxremains an explicit xAI route and still requires xAI.- Deep and Premium remain Gemini Deep Research paths.
- Explicit vendor-research refreshes still require their supported direct provider path.
- The curated recipe is cost-governed and hermetically tested, serving as the preferred single-key default route for standard research runs.
For the general key and approval rules, see API Key Setup and Run Modes and Costs.