Connecting OpenRouter as n8n's Model Backend

Q: 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.

Q: Do I need separate OpenRouter accounts per environment?

Not required. Separate keys and credit limits are usually enough for isolation.

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/v1 when 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-mini or anthropic/claude-sonnet-4.5 (verify current slugs at build).
Optional headers (when supported): HTTP-Referer for your app URL and X-Title / X-OpenRouter-Title for 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]
  → Slack

C. 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 :free models 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/model slugs, not only gpt-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: 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.

Summary

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/v1 when 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-mini or anthropic/claude-sonnet-4.5 (verify current slugs at build).
Optional headers (when supported): HTTP-Referer for your app URL and X-Title / X-OpenRouter-Title for 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]
  → Slack

C. 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 :free models 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/model slugs, not only gpt-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?

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?

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: 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.

Connecting OpenRouter as n8n's Model Backend

Search Documentation

Connecting OpenRouter as n8n's Model Backend