Connecting OpenRouter as n8n's Model Backend
Point n8n chat and agent nodes at OpenRouter so you can swap models, keep provider fallbacks, and align canvas agents with the same gateway your code uses.
Summary
Configure OpenRouter credentials (native OpenRouter chat model node, or OpenAI-compatible base URL https://openrouter.ai/api/v1), pick an explicit model slug, smoke-test a one-shot completion, then attach that model to AI Agent or chain nodes with spend and logging discipline.
Recipe
- Create an OpenRouter API key in the OpenRouter dashboard. Prefer a dedicated key for n8n with a credit limit.
- In n8n, add credentials:
- Prefer OpenRouter credential type when the node offers it, or
- OpenAI credential with API key = OpenRouter key and base URL overridden to
https://openrouter.ai/api/v1when the node allows base URL (verify UI at build).
- Drop an OpenRouter Chat Model node (or OpenAI Chat Model configured for OpenRouter) onto the canvas.
- Set model to a full slug such as
openai/gpt-4o-minioranthropic/claude-sonnet-4.5(verify current slugs at build). - Optional headers (when supported):
HTTP-Refererfor your app URL andX-Title/X-OpenRouter-Titlefor dashboard labeling. - Connect the model sub-node to AI Agent or use it in a simple chat chain. Run Manual Trigger once.
- Confirm the run log shows a completion and check OpenRouter Activity for the same request and cost.
- Document the model slug in the workflow description so teammates do not "fix" it silently.
Working Example
A. Minimal chat model path
Manual Trigger
→ OpenRouter Chat Model
credential: OpenRouter (n8n key)
model: openai/gpt-4o-mini
prompt: "Reply with pong"
→ Set / NoOp (inspect JSON)B. Agent path with tool-capable model
Webhook / Chat Trigger
→ AI Agent
Chat Model: OpenRouter → anthropic/claude-sonnet-4.5 (verify slug)
tools: [one HTTP tool]
→ SlackC. Parity check outside n8n
import os
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
default_headers={
"HTTP-Referer": "https://your-company.example", # optional
"X-OpenRouter-Title": "n8n-parity-check",
},
)
resp = client.chat.completions.create(
model="openai/gpt-4o-mini", # same slug as the n8n node
messages=[{"role": "user", "content": "Reply with pong"}],
)
print(resp.choices[0].message.content)
print(resp.usage)If Python works and n8n fails, the bug is credentials, base URL, or node wiring - not OpenRouter account health.
D. OpenAI-compatible base URL pattern
When a node only knows "OpenAI":
| Field | Value |
|---|---|
| API Key | sk-or-v1-... (OpenRouter) |
| Base URL | https://openrouter.ai/api/v1 |
| Model | OpenRouter slug (provider/model) |
Do not paste an OpenRouter key into a credential that still targets https://api.openai.com/v1.
Deep Dive
Why OpenRouter behind n8n
| Benefit | Detail |
|---|---|
| Model mobility | Change slugs without new vendor credentials per provider |
| Unified billing view | Activity/API usage next to your coded agents |
| Provider fallback | Multi-host models keep completing when one host fails |
| Eval alignment | Same gateway in CI scripts and canvas pilots |
Credential isolation
| Key | Use |
|---|---|
n8n-dev | Builders' sandboxes, low credit cap |
n8n-prod | Production workflows only, alerting on burn |
ci-eval | Offline golden tests in Python/CI |
Rotate keys if a workflow export or screenshot may have leaked them.
Model selection for agent nodes
- Prefer models with documented tool calling when using AI Agent + tools.
- Use cheaper slugs for classification and formatting nodes.
- Keep a second slug written in the runbook for incidents (manual switch).
- Re-verify free-tier or
:freemodels before relying on them in prod; capacity and tool support vary.
Observability bridge
n8n shows node input/output. OpenRouter shows tokens, cost, provider, and model served.
Log a correlation id (webhook request id) into the prompt metadata or a Set field so you can join a failed Slack post to the exact generation later.
Privacy and data policy
If prompts contain sensitive data, apply OpenRouter privacy / data-collection preferences on the account or per request where the API allows it.
Self-hosted n8n does not remove the fact that prompt content still goes to the model provider OpenRouter routes to.
Gotchas
- Wrong base URL with OpenRouter key. Requests hit OpenAI and fail auth or bill the wrong place.
- Bare model names. OpenRouter expects
vendor/modelslugs, not onlygpt-4o-mini, unless a node rewrites them (do not assume). - Tool calling mismatches. Some models accept chat but fail tool loops. Test with a forced tool prompt.
- Shared unlimited key. One runaway workflow can exhaust credits for every agent in the company.
- Header support gaps. Not every n8n model node exposes custom headers; attribution may be incomplete (verify at build).
- Cached wrong credential. After editing a key, re-select the credential on the node and re-run.
- Assuming n8n surfaces
usage.cost. You may need OpenRouter Activity or an HTTP poll of usage APIs for cost dashboards.
Alternatives
| Backend | Pros | Cons |
|---|---|---|
| OpenRouter | Multi-model, fallbacks, one key shape | Extra platform to govern |
| Direct OpenAI/Anthropic/Google nodes | First-party features | Credential sprawl, weaker multi-vendor swap |
| Self-hosted Ollama node | Data stays local | Ops burden; weaker tool ecosystem |
| HTTP Request to any API | Full control | You build retries, parsing, auth |
| Your agent microservice | Best long-term product path | Higher build cost |
FAQs
Is there a dedicated OpenRouter node in n8n?
n8n's AI ecosystem has included OpenRouter chat model integrations and OpenAI-compatible paths. Exact node names vary by version - search "OpenRouter" in the node picker and confirm against current n8n docs at build.
Can I use provider order and models fallback arrays from n8n?
Only if the node forwards OpenRouter-specific body fields. Many visual nodes expose model + temperature only. For full routing objects, call OpenRouter via HTTP Request or move that path to code.
How do I cap spend for n8n?
Create an OpenRouter key with a credit limit (and reset policy if available), monitor Activity, and keep max iterations low on agent nodes.
Why does the agent work without tools but fail with tools?
Often the model/provider path does not support the tool schema the agent node sends, or the credential path strips needed fields. Bisect with a tool-capable first-party model, then reintroduce OpenRouter.
Should every n8n workflow use the same model?
No. Classify and format on small models; reserve stronger slugs for tool-heavy agents. Record the matrix in the workflow description.
Can OpenRouter replace having SaaS app credentials?
No. OpenRouter only serves models. Gmail, Slack, CRM, and HTTP APIs still need their own n8n credentials.
How do I migrate this setup into code later?
Keep system prompts, model slugs, and tool URLs in a shared doc. The Python OpenAI client against OpenRouter is a near-copy of what the node does.
Is streaming required?
Not for most automations. Batch request/response is enough for triage and drafting. Streaming matters more for chat UIs.
What rate limits apply?
OpenRouter account and upstream provider limits both apply. Back off on 429s; reduce parallel workflow executions if you burst.
Do I need separate OpenRouter accounts per environment?
Not required. Separate keys and credit limits are usually enough for isolation.
Related
Related: Building an AI Agent Node Workflow in n8n
Related: No/Low-Code Orchestration Basics
Related: From No-Code Prototype to Custom Code: A Migration Path
Related: No/Low-Code Orchestration Best Practices
Related: How OpenRouter's Provider Fallback Actually Protects Uptime
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.