n8n-nodes-unified-ai

Unified multi-provider AI node for n8n with deterministic routing, schema validation, retries, fallback, caching, and structured metrics across OpenAI, Anthropic, and Gemini.

V1 scope

• One node with two modes:
  • Task (default, production path)
  • Chat / Agent-lite (memory only during node execution)
• Providers:
  • OpenAI (/chat/completions)
  • Anthropic (/messages)
  • Gemini (generateContent)
• Routing inputs:
  • taskType
  • priority (cost|latency|quality)
  • budgetUsdMax
  • latencyMsMax
  • minQualityTier
• JSON reliability loop:
  • Attempt 1: chosen model
  • Attempt 2: same model with repair prompt + validation errors
  • Attempt 3: fallback model
  • Failure -> dead-letter output
• Cache backends:
  • memory (LRU)
  • Redis
  • Postgres
  • SQLite
• Log sinks:
  • stdout
  • webhook
  • PostHog
  • Postgres

Install

npm install
npm run build

Pack/publish as a normal n8n community node package (n8n-nodes-unified-ai).

Credentials

Create Unified AI API credential and provide any subset of:

• OpenAI API Key
• Anthropic API Key
• Gemini API Key

Base URLs are configurable for proxy/self-hosted gateways.

Node outputs

• Output 0 (main): valid result payload
• Output 1 (error): dead-letter payload with trace, input, errors, and raw output

Task mode contract

Inputs:

• taskType
• instructions
• inputSource: json | binary | jsonAndBinary
• context (JSON, when using JSON input)
• data (JSON, when using JSON input)
• binaryProperty + parse controls (when using binary input)
• outputSchema (optional JSON Schema)

Binary parse controls:

• binaryParseStrategy: auto | text | base64 | metadataOnly
• maxBinaryKb
• maxBinaryTextChars
• maxBinaryBase64Chars

The node adds binary metadata into the prompt and can include extracted text/base64 (truncated by your limits).

Output JSON includes:

• result
• raw
• usage (inputTokens, outputTokens, costUsd, latencyMs)
• modelChosen
• retries
• cacheHit
• traceId
• inputSource
• binary (metadata when binary input is used)

Parameter layout

Top-level fields are now minimal for common usage. Advanced controls are grouped into:

• Model Options
• Reliability Options
• Cache Options
• Logging Options
• Execution Options

Model Options now includes Allowed Models (multi-select) so you can restrict routing to a specific model range and avoid unavailable models in your environment.
You can also use Custom Allowed Models (comma/newline separated) to use newly released models immediately.

• Supports provider:model (recommended), e.g. gemini:gemini-2.5-flash
• Supports plain names, e.g. gpt-5.2 (provider is auto-inferred)

Notes

• Tool calling and streaming are intentionally not in V1.
• Routing model catalog and costs are in /src/lib/providerCatalog.ts for easy tuning.