@auwra/n8n-nodes-ai-router

An n8n community node that automatically routes each prompt to the best AI model across Anthropic, OpenAI, Google Gemini, Mistral AI, Groq, and local Ollama — based on what the task actually needs.

Instead of hardcoding one model, the AI Router detects whether a prompt is a coding task, analysis, creative writing, summarization, vision, or chat, then picks the optimal model for your priority: cheapest, fastest, highest quality, or balanced. It falls back to the next-best model automatically if the first one fails.

Table of contents

• Quick start
• Installation
• Configuration
• How routing works
• Choosing the right mode
• Model registry
• Keeping the registry up to date
• Adding a custom model
• Example workflows
• Changelog
• Contributing
• License

Quick start

1. Install the node (see Installation)
2. Add the AI Router node to any workflow
3. Set up credentials — paste in at least one API key (Groq has a free tier)
4. Connect your prompt source and run

That's it. The node detects the task, picks the best model, calls it, and returns response. No configuration required for basic use.

Installation

Via n8n Community Nodes UI (recommended)

1. Go to Settings → Community Nodes
2. Click Install
3. Enter @auwra/n8n-nodes-ai-router
4. Click Install and restart if prompted

Via npm (self-hosted)

cd ~/.n8n
npm install @auwra/n8n-nodes-ai-router
# Restart n8n

Credentials setup

The node uses a single credential object called AI Router Credentials that holds all your API keys in one place. Fill in only the providers you have — the router automatically skips providers with no key.

| Field | Where to get it | |---|---| | Anthropic API Key | console.anthropic.com | | OpenAI API Key | platform.openai.com | | Google Gemini API Key | aistudio.google.com | | Mistral AI API Key | console.mistral.ai | | Groq API Key (free tier) | console.groq.com | | Ollama Base URL | http://localhost:11434 (no key needed) |

One provider is enough to get started. Groq is the easiest: free tier, no credit card.

Configuration

Input

| Parameter | Type | Default | Description | |---|---|---|---| | Prompt | string | — | The user message to send to the AI model | | System Prompt | string | — | Optional system-level instruction: persona, output format, constraints | | Temperature | number | 0.7 | Sampling temperature 0–2. 0 = deterministic, 2 = very creative. Ignored by reasoning models. |

Routing

| Parameter | Type | Default | Description | |---|---|---|---| | Routing Mode | enum | auto | How to prioritise model selection | | Task Hint | enum | auto-detect | Override automatic task detection |

Filtering / budget

| Parameter | Type | Default | Description | |---|---|---|---| | Allowed Providers | multiselect | all | Which providers are eligible | | Max Cost Per 1K Tokens | number | 0 (no limit) | Hard budget cap in USD — models above this are excluded |

Generation

| Parameter | Type | Default | Description | |---|---|---|---| | Max Tokens | number | 0 (provider default) | Maximum tokens to generate |

Behaviour

| Parameter | Type | Default | Description | |---|---|---|---| | Enable Fallback | boolean | true | Retry with next-best model on 429/5xx errors (up to 3 attempts) | | Dry Run (Routing Only) | boolean | false | Select the best model and return routing info but do NOT call any API — no tokens spent | | Max Items Per Execution | number | 10 | Hard cap on items per run. Set to 0 to disable. |

Output options

| Parameter | Type | Default | What it adds to output | |---|---|---|---| | Include Model Info | boolean | false | modelUsed, providerUsed, attemptsTaken, inputTokens, outputTokens | | Include Detected Task | boolean | false | detectedTask, detectedTaskConfidence | | Include Score Breakdown | boolean | false | scoreBreakdown — top-3 candidates with final score and per-criterion sub-scores | | Include Estimated Cost | boolean | false | estimatedCostUSD — calculated from token counts × registry pricing |

Routing modes

| Mode | Best for | What it optimises | |---|---|---| | auto | General-purpose workflows | Balanced mix of quality, cost, and speed | | quality | Critical outputs, production content | Task-specific model quality above all else | | cost | High-volume, budget-sensitive workflows | Cheapest model that can do the job | | speed | Real-time, latency-sensitive workflows | Lowest-latency model first | | local | Privacy-sensitive data, offline use | Ollama only — zero cost, no data leaves your machine |

Task hint values

| Value | Auto-detected when prompt contains | |---|---| | coding | Code snippets, language names, file extensions, debug/refactor/implement | | writing | write/draft/compose + document type (email, blog, essay, story, ad copy…) | | analysis | analyze, evaluate, compare, pros and cons, explain why, root cause | | summarization | summarize, tl;dr, key points, in N bullets, executive summary | | classification | classify, categorize, sentiment, true/false, spam detection | | vision | Image URLs, base64 image data, OCR, visual content | | embeddings | embed, vector, semantic search, RAG, cosine similarity | | chat | Greetings, open-ended questions (default fallback) |

How routing works

flowchart TD
    A([Prompt received]) --> B{Task hint set?}
    B -- Yes --> D[Use hint as task type]
    B -- No --> C[taskDetector\nweighted regex patterns]
    C --> D
    D --> E[scoreModels\nfilter + score all candidates]

    E --> F{allowedProviders filter}
    F --> G{maxCostPer1K budget cap}
    G --> H{capability requirements\nvision / embeddings}
    H --> I{context window\n≥ prompt length}
    I --> J[Score each model\ntaskFit · cost · latency · contextSize]
    J --> K[Sort descending — best first]

    K --> L[executeWithFallback\nattempt 1: top model]
    L -- success --> M([Output])
    L -- 429 / 5xx / network --> N{fallback enabled?}
    N -- Yes --> O[attempt 2: next model]
    O -- success --> M
    O -- fail --> P[attempt 3: next model]
    P -- success --> M
    P -- all fail --> Q([Error])
    N -- No --> Q
    L -- 400 / 401 / 403 --> Q

Scoring formula

Each candidate model gets a score (0–1):

score = w_taskFit  × taskAffinity[task]
      + w_cost     × (1 − blendedPer1K / maxInPool)
      + w_latency  × (1 − (latencyTier − 1) / 2)
      + w_context  × log(contextWindow + 1) / log(maxInPool + 1)

Context uses log normalization so a single model with a huge context window (e.g. 10M tokens) doesn't collapse every other model's score to near zero.

Weights by mode:

| Mode | taskFit | cost | latency | contextSize | |---|---|---|---|---| | auto | 0.35 | 0.25 | 0.20 | 0.20 | | quality | 0.70 | 0.05 | 0.05 | 0.20 | | cost | 0.20 | 0.60 | 0.10 | 0.10 | | speed | 0.25 | 0.15 | 0.50 | 0.10 | | local | 0.40 | 0.40 | 0.10 | 0.10 |

Choosing the right mode

Use quality when: output accuracy matters (production content, customer-facing responses, complex reasoning). The router will pick the model most specialised for the detected task — Claude Opus for analysis, Devstral for code, Gemini Pro for vision.

Use cost when: you're running high volume and the task is simple (classification, summarization, short chat). Expect Groq or Gemini Flash Lite to win most of the time.

Use speed when: you need sub-second responses (real-time chat, live autocomplete). All tier-1 models are fast; the router picks the most capable one among them.

Use auto when: you're unsure. It's a sensible middle ground — it won't pick the most expensive model for a simple greeting, but it won't use the cheapest one for a complex analysis either.

Use local when: prompts contain sensitive data you can't send to cloud APIs, or you're working offline.

Combine mode with Allowed Providers for precise control: quality mode with only anthropic + openai ensures only flagship models are used.

Model registry

Pricing verified April 2026. blendedPer1K = (input×0.7 + output×0.3) / 1000.

Anthropic

| Model ID | Input/1M | Output/1M | Context | Best for | |---|---|---|---|---| | claude-opus-4-6 | $5.00 | $25.00 | 1M | Complex analysis, deep reasoning | | claude-sonnet-4-6 | $3.00 | $15.00 | 1M | Balanced quality across all tasks | | claude-haiku-4-5-20251001 | $1.00 | $5.00 | 200K | Fast chat, classification, vision |

OpenAI

| Model ID | Input/1M | Output/1M | Context | Best for | |---|---|---|---|---| | gpt-4.1 | $2.00 | $8.00 | 1M | General chat, coding, vision | | gpt-4o | $2.50 | $10.00 | 128K | Multimodal, vision-heavy tasks | | o3 | $2.00 | $8.00 | 200K | Deep reasoning, complex analysis (no streaming) | | o4-mini | $1.10 | $4.40 | 200K | Cheaper reasoning, STEM, code | | gpt-4o-mini | $0.15 | $0.60 | 128K | Cheap chat, classification, vision |

Google Gemini

| Model ID | Input/1M | Output/1M | Context | Best for | |---|---|---|---|---| | gemini-3.1-pro-preview | $2.00 | $12.00 | 1M | Cutting-edge quality (preview) | | gemini-2.5-pro | $1.25 | $10.00 | 1M | Long-context analysis, vision | | gemini-3-flash-preview | $0.50 | $3.00 | 1M | Fast next-gen tasks (preview) | | gemini-2.5-flash | $0.30 | $2.50 | 1M | Fast summarization, cheap vision | | gemini-2.5-flash-lite | $0.10 | $0.40 | 1M | Ultra-cheap classification |

Mistral

| Model ID | Input/1M | Output/1M | Context | Best for | |---|---|---|---|---| | mistral-large-2512 | $0.50 | $1.50 | 262K | Cost-efficient coding, analysis | | mistral-medium-3 | $0.40 | $2.00 | 131K | Balanced general tasks | | mistral-small-4-0-26-03 | $0.10 | $0.30 | 262K | Creative writing, chat | | devstral-2-25-12 | $0.10 | $0.30 | 256K | Code generation (SWE-bench 72.2%) |

Groq (ultra-fast inference)

| Model ID | Input/1M | Output/1M | Context | Best for | |---|---|---|---|---| | moonshotai/kimi-k2-instruct | $1.00 | $3.00 | 1M | Long-context analysis, agentic | | llama-3.3-70b-versatile | $0.59 | $0.79 | 128K | Low-latency general tasks | | qwen/qwen3-32b | $0.29 | $0.59 | 128K | Coding, multilingual, reasoning | | openai/gpt-oss-120b | $0.15 | $0.60 | 128K | Balanced quality at ~500 t/s | | meta-llama/llama-4-scout-17b-16e-instruct | $0.11 | $0.34 | 10M | Huge-context vision, ultra-cheap | | openai/gpt-oss-20b | $0.075 | $0.30 | 128K | Fastest throughput (~1000 t/s) | | llama-3.1-8b-instant | $0.05 | $0.08 | 128K | Cheapest, sub-100ms responses |

Ollama (local)

Any model you've pulled via ollama pull <model> works. Set Ollama Model to the model name and Ollama Base URL to your instance address.

Keeping the registry up to date

Provider APIs change quickly. Use the built-in sync script to check for stale or new model IDs:

npm run build
npm run sync:models

The script hits each provider's live /models endpoint and reports:

• Stale — IDs in the registry that no longer exist
• New — IDs available on the provider not yet in the registry

What must still be updated manually in modelRegistry.ts:

• Pricing (check each provider's pricing page)
• Task affinity scores
• Latency tier and context window size

Recommended cadence: run sync:models monthly or after a major model release.

Adding a custom model

Edit only one file: nodes/AiRouter/router/modelRegistry.ts. Append a new entry to MODEL_REGISTRY:

{
  id: 'your-model-api-id',   // exact string sent in API requests
  provider: 'openai',         // must match an existing ProviderType
  displayName: 'My Model',
  pricing: {
    inputPer1M: 1.00,
    outputPer1M: 4.00,
    blendedPer1K: 0.0019,   // (1.00×0.7 + 4.00×0.3) / 1000
  },
  capabilities: {
    supportsVision: false,
    supportsEmbeddings: false,
    supportsStreaming: true,
    supportsReasoningMode: false,
    isLocal: false,
    contextWindow: 128_000,
  },
  latencyTier: 1,             // 1=fast  2=moderate  3=slow/reasoning
  taskAffinity: {
    coding: 0.88,
    chat: 0.85,
    // Omit tasks where the model has no particular strength (defaults to 0.5)
  },
},

Then rebuild: npm run build

For a new provider (new API format), see CONTRIBUTING.md.

Example workflows

Basic chatbot with smart routing

1. Webhook → receives { "message": "..." }
2. AI Router
   • Prompt: {{ $json.message }}
   • Mode: auto
   • Enable Fallback: on
3. Respond to Webhook → {{ $json.response }}

The router detects whether the message is a coding question, analysis request, or casual chat and picks accordingly.

Quality-first content pipeline

1. Schedule Trigger → fires daily
2. HTTP Request → fetches data to process
3. AI Router
   • Prompt: Analyze the following data and write a professional summary: {{ $json.data }}
   • Mode: quality
   • Allowed Providers: Anthropic, OpenAI, Google
   • Include Model Info: on
4. Google Sheets → saves response, modelUsed, token counts

Mode quality with flagship providers ensures you always get the best model for the task. Token counts let you track spend.

Budget-capped high-volume classification

1. Spreadsheet Trigger → rows to classify
2. AI Router
   • Prompt: Classify this support ticket as "billing", "technical", or "general": {{ $json.ticket }}
   • Task Hint: classification
   • Mode: cost
   • Max Cost Per 1K Tokens: 0.001
   • Max Items Per Execution: 100
3. Spreadsheet → write back {{ $json.response }}

Hard-coding classification as the task hint skips detection overhead and ensures the cost-efficient classification models are preferred. The budget cap keeps costs bounded.

Full output (all options enabled)

{
  "response": "Here is the TypeScript function you requested:\n\n```typescript\nfunction debounce...",
  "modelUsed": "devstral-2-25-12",
  "providerUsed": "mistral",
  "attemptsTaken": 1,
  "inputTokens": 25,
  "outputTokens": 459,
  "estimatedCostUSD": 0.0000073,
  "detectedTask": "coding",
  "detectedTaskConfidence": 0.91,
  "scoreBreakdown": [
    { "model": "devstral-2-25-12",            "provider": "mistral", "score": 0.9289, "breakdown": { "taskFit": 1.000, "cost": 0.985, "latency": 0.500, "contextSize": 0.772 } },
    { "model": "moonshotai/kimi-k2-instruct", "provider": "groq",    "score": 0.8800, "breakdown": { "taskFit": 0.880, "cost": 0.855, "latency": 1.000, "contextSize": 0.857 } },
    { "model": "o3",                          "provider": "openai",   "score": 0.8632, "breakdown": { "taskFit": 0.970, "cost": 0.655, "latency": 0.000, "contextSize": 0.757 } }
  ]
}

Dry-run output

When Dry Run is enabled, no API call is made and the output is:

{
  "dryRun": true,
  "selectedModel": "devstral-2-25-12",
  "selectedProvider": "mistral",
  "selectedScore": 0.9289,
  "detectedTask": "coding",
  "detectedTaskConfidence": 0.91,
  "scoreBreakdown": [ ... ]
}

Changelog

v0.1.6

• Add: System Prompt parameter — optional system-level instruction passed to all providers
• Add: Temperature parameter (0–2, default 0.7) — ignored automatically for reasoning models
• Add: Dry Run toggle — returns routing decision without spending any tokens; includes selected model, score, detected task, and score breakdown
• Add: Include Detected Task output option — exposes detectedTask and detectedTaskConfidence in the output
• Add: Include Score Breakdown output option — exposes top-3 ranked candidates with final scores and per-criterion sub-scores (taskFit, cost, latency, contextSize)
• Add: Include Estimated Cost output option — computes estimatedCostUSD from token counts × registry pricing

v0.1.5

• Fix: Quality mode now reliably selects flagship models — context score uses log normalization (prevents a single 10M-context model from collapsing all 1M-context scores to 0.1), and quality-mode weights raised taskFit to 0.70
• Add: Max Items Per Execution parameter (default 10) — hard cap on items processed per run to prevent cost drain from accidental loops or large batches

v0.1.4

• Fix: Anthropic requests no longer hang indefinitely — timeout now correctly catches AbortError in Node.js
• Fix: max_tokens always included in Anthropic requests (required by the API)
• Fix: Anthropic responses from reasoning models parsed correctly — text block found by type, not position

v0.1.2

• Initial public release

Contributing

See CONTRIBUTING.md for:

• How to add a new model (one object in an array)
• How to add a new provider adapter
• Commit conventions
• How to test locally

License

MIT