n8n-nodes-openrouter-pro

Professional n8n community nodes for OpenRouter and any
OpenAI-compatible API.

Need a custom n8n workflow?

Get professional n8n development & automation support at
https://tally.so/r/q4q1L9.

Table of Contents

• Why OpenRouter Pro?
• Overview
• Features
• Installation
• Quick Start
• Credentials
  • Base URL — use any OpenAI-compatible endpoint
• Node Reference
  • Chat: Generate a Completion
  • Thinking / Reasoning mode
  • Get Models
• Output Shape
• OpenRouter-only capabilities
• Examples
• Development
• Troubleshooting
• License

Why OpenRouter Pro?

One node to talk to every major LLM — with the freedom to switch models,
providers, or even your entire AI backend without rebuilding a single
workflow.

What it does for your business:

• One node, hundreds of models. GPT, Claude, Gemini, Llama, DeepSeek,
  Mistral, Qwen and 300+ more through OpenRouter.
  Change models from a dropdown — prompts, history and logic stay untouched.
• Lower LLM costs, automatically. Route by price or latency,
  allow-list only the providers you trust, and set model fallbacks so
  cheaper models take over when a premium one is unavailable. Exact token usage
  is reported on every response, so spend stays visible and audit-able.
• Zero vendor lock-in. The node is a thin OpenAI-compatible client. Point
  the Base URL at LiteLLM, Azure, ollama, your own gateway — or an on-prem
  endpoint for compliance — and the same workflows keep working.
• Ready for the newest model capabilities. First-class reasoning /
  thinking mode, tool calling, vision input and structured
  (JSON Schema) output, so your automations can use each model's strength.
• Production-grade engineering. Built the way n8n's own production nodes
  are — typed request/response handling, a live model dropdown, Continue On Fail and correct pairedItem linking — so it behaves predictably in
  real workflows and plays nicely with the rest of your n8n stack.

Overview

The OpenRouter node gives you a single n8n node to talk to hundreds of
LLMs (GPT, Claude, Llama, DeepSeek, Gemini, Mistral, Qwen, …) through
OpenRouter — and, thanks to a fully
OpenAI-compatible design, to any
other OpenAI-compatible endpoint (LiteLLM, ollama, llama.cpp, Azure OpenAI, a
company gateway or proxy, …) by simply changing the Base URL in the
credentials.

The node is built the way n8n's own production nodes are: programmatic style
with typed request/response models, loadOptions for the live model list,
Continue On Fail support, and proper pairedItem linking.

Features

• Chat completions against {baseUrl}/chat/completions (OpenAI-compatible).
• Thinking / Reasoning mode with OpenAI-style effort levels
  (minimal → max), an Anthropic-style reasoning-token cap, and optional
  exclusion of reasoning from the response.
• Model fallbacks (OpenRouter models array) — automatically fall back to
  cheaper or more available models.
• Provider routing (OpenRouter) — order providers by price/latency/etc.,
  allow-list or ignore specific provider slugs, and opt into route: "fallback".
• Dynamic model dropdown — the Model field is populated live from the API,
  but still accepts any typed model ID (required for custom endpoints).
• Multimodal input — attach images to the prompt as URLs or data: URLs.
• Tool / function calling — pass a JSON tool list and control tool_choice.
• Structured output — JSON object or a full JSON Schema response format.
• Full OpenAI sampling controls — temperature, top_p, top_k, penalties,
  stop sequences, seed, max tokens.
• Rich output shaping — Simplified object, full raw response, or text only.
• List Models operation — inspect models, context lengths, pricing, and
  modalities on your endpoint.
• Credential testing — the credential is validated against GET /models
  when you save it.

Installation

There are two ways to install the node: from the n8n UI as a Community Node
(recommended), or manually (npm / local folder / dev mode).

Option 1 — Install from the n8n UI (Community Nodes)

Community Nodes installation runs on a self-hosted n8n instance with community
nodes enabled:

1. Open your n8n instance and go to Settings → Community Nodes.
2. Click Install a community node.
3. Choose From npm, enter n8n-nodes-openrouter-pro, and click Install.
4. n8n downloads the package and reloads automatically.
5. The node appears in the node panel under OpenRouter.

Note: community nodes are enabled by default on self-hosted n8n (they can
be disabled with N8N_COMMUNITY_NODES_ENABLED=false) and are only available
on paid plans on n8n Cloud.

Option 2 — Manual installation

Install into your n8n instance (npm):

# from the directory where your self-hosted n8n runs
npm install n8n-nodes-openrouter-pro

Then restart n8n. The node appears in the node panel under OpenRouter.

Install as a local node package (custom folder):

# copy (or symlink) the built package into n8n's custom nodes folder
mkdir -p ~/.n8n/custom
cp -r /path/to/n8n-nodes-openrouter-pro ~/.n8n/custom/

Restart n8n — the node is then bundled with the instance.

Run it in dev mode (from this repository):

# from this repository
npm install
npm run dev            # starts n8n with the node loaded + hot reload

Community node verification — as with any community node, install it on
a non-production instance first and review the source. See
n8n community nodes.

Quick Start

1. Create a credential: OpenRouter (or any OpenAI-compatible API).
2. Paste an OpenRouter API key from openrouter.ai/keys.
   Leave the Base URL as https://openrouter.ai/api/v1.
3. Add an OpenRouter node to your workflow.
4. Pick a model (e.g. openai/gpt-4o) and enter a prompt.
5. Connect the output to a Set node or the editor preview to see the answer in
   json.content.

That's it — sk-or-… keys "just work" against the default Base URL.

Credentials

The credential performs a test request to GET {baseUrl}/models to validate
the key when you save it.

Base URL — use any OpenAI-compatible endpoint

Because the node is a thin, OpenAI-compatible client, the Base URL decides
what you talk to. Nothing else changes.

Tip: When you point the node at a non-OpenRouter endpoint, leave the
Thinking / Reasoning and OpenRouter Routing groups empty — those
fields are OpenRouter-specific and would otherwise be sent to endpoints that
don't understand them. The node only sends a field when you actually set it.

Node Reference

Chat: Generate a Completion

The primary operation. Parameters:

Thinking / Reasoning mode

Reasoning-capable models (DeepSeek R1, o-series, Claude 3.7 Sonnet with
extended thinking, …) spend tokens "thinking" before answering. Enable it under
Thinking / Reasoning:

The reasoning text is returned in the reasoning field of the simplified
output (or message.reasoning on the raw response), so you can log it,
summarize it, or feed it to another model.

Get Models

Lists the models available on the configured endpoint. Each model is returned
as its own output item with its full metadata (id, name, context length,
pricing, modalities, description, …). Useful for audit scripts, capacity
checks, or building custom "best model" logic.

Output Shape

With the default Simplified output, the node returns a single item:

{
  "content": "The final answer text…",
  "reasoning": "Optional chain-of-thought from reasoning models…",
  "reasoningSummary": ["…", "…"],           // OpenRouter reasoning summaries
  "role": "assistant",
  "model": "openai/gpt-4o",                 // model actually used (post-fallback)
  "servedBy": "Together AI",                // provider that served it (OpenRouter)
  "finishReason": "stop",
  "id": "gen-…",
  "object": "chat.completion",
  "created": 1730000000,
  "usage": {
    "inputTokens": 42,
    "outputTokens": 96,
    "reasoningTokens": 31,                  // when the model reasoned
    "totalTokens": 138
  },
  "raw": { /* the complete raw API response */ }
}

• Text Only → { "content": "…" } (great when you only need the answer).
• Full Response → the exact body OpenRouter/your endpoint returned.

OpenRouter-only capabilities

These live in the OpenRouter Routing group and are ignored unless set:

• Provider Order — provider.order: ["price" | "latency" | "throughput" | "quality"].
• Allow Only Providers / Ignore Providers — comma-separated provider
  slugs → provider.allow / provider.ignore.
• Route: Fallback — route: "fallback" keeps trying providers until one
  succeeds.
• Fallback Models — the models array for automatic model fallback.
• Top K / Repetition Penalty — OpenRouter-native sampling options.

See the OpenRouter docs
for details.

Examples

Summarize an article

[HTTP Request] → [OpenRouter] → [Set]
                    ├ model:          anthropic/claude-3.7-sonnet
                    ├ System Message: You are a terse editor.
                    ├ Prompt:         {{ $json.text }}
                    └ Simplify:       Text Only

Multi-turn chat with reasoning

[Webhook] → [OpenRouter]
              ├ Model:              deepseek/deepseek-r1
              ├ Thinking Mode:      Effort → High
              ├ Additional Messages: {{ $json.history }}
              └ Prompt:             {{ $json.question }}

Read the assistant's thinking from json.reasoning before the final answer in
json.content.

JSON output you can pipe straight into a database

[OpenRouter]
  ├ System Message: Reply with JSON only.
  ├ Options → Response Format: JSON Schema
  ├ Options → JSON Schema: {"type":"object","properties":{"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}},"required":["title","tags"]}
  └ Prompt: Summarize {{ $json.body }}

Development

npm install          # install dependencies (includes @n8n/node-cli)
npm run dev          # build in watch mode + start n8n with the node
npm run lint         # check code style / errors
npm run lint:fix     # auto-fix what can be fixed
npm test             # run the unit tests (vitest)
npm run build        # compile TypeScript to dist/
npm run release      # lint + build + version bump + tag (triggers publish)

Project structure

n8n-nodes-openrouter-pro/
├── credentials/
│   └── OpenRouterApi.credentials.ts   # API key, Base URL, headers
├── nodes/
│   └── OpenRouter/
│       ├── OpenRouter.node.ts         # node UI definition + execute() logic
│       ├── OpenRouterModel.ts         # typed request/response models
│       ├── OpenRouterModels.ts        # model dropdown definition
│       ├── OpenRouterUtils.ts         # pure helpers (unit-tested)
│       └── methods/
│           └── loadOptions.ts         # live model list
└── test/
    └── OpenRouterUtils.test.ts        # unit tests (vitest)

Troubleshooting

License

MIT © 2026

Built with the n8n community node template.