Configure @ai-sdk/openai for n4n.ai in 5 minutes

To configure ai-sdk openai provider for n4n.ai, you point Vercel’s @ai-sdk/openai package at the gateway’s OpenAI-compatible endpoint and supply a gateway API key. The change is tiny, but it puts 240+ models behind one interface and lets the gateway handle fallback, routing, and per-token metering without extra code.

Step 1: Scaffold a TypeScript project

Start clean. The AI SDK is ESM-first, so use Node 20+ and a proper tsconfig.

mkdir n4n-ai-sdk-demo && cd n4n-ai-sdk-demo
npm init -y
npm install ai @ai-sdk/openai zod
npm install -D typescript tsx @types/node

Create tsconfig.json with bundler module resolution:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Use tsx to run TypeScript directly during development. No build step required for verification.

Step 2: Store credentials and gateway URL

Never hard-code keys. Put them in .env and load via Node’s --env-file flag (Node 20.6+) or dotenv.

echo "N4N_API_KEY=sk-your-gateway-key" > .env
echo "N4N_BASE_URL=https://api.n4n.ai/v1" >> .env

If you use a shell without env-file support, prepend eval $(cat .env | sed 's/^/export /') or install dotenv. The base URL is the single OpenAI-compatible endpoint the gateway exposes.

Step 3: Instantiate the OpenAI provider against the gateway

When you configure ai-sdk openai provider for n4n.ai, the only required deviation from the standard OpenAI setup is the baseURL. The apiKey is your gateway key, not an OpenAI key.

// src/client.ts
import { openai } from '@ai-sdk/openai';

const n4nProvider = openai({
  baseURL: process.env.N4N_BASE_URL!,
  apiKey: process.env.N4N_API_KEY!,
  // The gateway is OpenAI-compatible; no compatibility shims needed.
});

// Model IDs follow the gateway's "provider/model" convention.
export const claude = n4nProvider('anthropic/claude-3.5-sonnet');
export const gpt4o = n4nProvider('openai/gpt-4o');

The gateway honors client routing directives and forwards provider cache-control hints. If you need to pin a provider or set cache behavior, pass headers through the provider factory:

const n4nPinned = openai({
  baseURL: process.env.N4N_BASE_URL!,
  apiKey: process.env.N4N_API_KEY!,
  headers: {
    'X-Cache-Control': 'max-age=3600',
  },
});

Model IDs are strings; any model the gateway addresses works. Missing models return a clean error from the gateway, not a crash in the SDK.

Step 4: Send a non-streaming completion

Use generateText from the ai core package. It returns the full text and a usage object with token counts.

// src/run.ts
import { generateText } from 'ai';
import { gpt4o } from './client';

async function main() {
  const { text, usage, finishReason } = await generateText({
    model: gpt4o,
    system: 'You are a senior network engineer.',
    prompt: 'Explain the difference between TCP and UDP in one paragraph.',
    temperature: 0.2,
  });

  console.log(text);
  console.log(`Tokens: ${usage.promptTokens} prompt, ${usage.completionTokens} completion`);
  console.log(`Finish: ${finishReason}`);
}

main().catch((err) => {
  console.error('Request failed:', err);
  process.exit(1);
});

Run it:

npx tsx src/run.ts

You should see a paragraph and token counts. The usage object is populated by the gateway’s per-token metering, so the numbers reflect what the gateway actually billed.

Step 5: Stream tokens to the client

For chat UIs, stream. streamText returns a textStream async iterable.

// src/stream.ts
import { streamText } from 'ai';
import { claude } from './client';

async function main() {
  const result = await streamText({
    model: claude,
    prompt: 'Write a haiku about distributed systems.',
  });

  for await (const delta of result.textStream) {
    process.stdout.write(delta);
  }
  console.log('\n---');
  console.log('Usage:', await result.usage);
}

main().catch(console.error);

The gateway’s automatic fallback means if the primary provider behind anthropic/claude-3.5-sonnet is rate-limited, the gateway substitutes a degraded-equivalent model and the stream continues. Your SDK code does not change.

Step 6: Verify success and inspect metering

Two checks confirm the wiring:

1. Model list reachable – curl the gateway’s OpenAI-compatible models endpoint:

curl -s -H "Authorization: Bearer $N4N_API_KEY" \
  $N4N_BASE_URL/models | head -c 200

You should get a JSON list containing entries like openai/gpt-4o. If this fails, your key or base URL is wrong.

2. Token usage non-zero – in the generateText run, usage.totalTokens must be > 0. If it’s zero, the request didn’t reach the gateway or the model returned empty.

Step 7: Handle errors and rate limits

The SDK throws typed errors. Wrap calls:

import { generateText } from 'ai';
import { APIError } from '@ai-sdk/openai';

try {
  await generateText({ model: gpt4o, prompt: 'test' });
} catch (e) {
  if (e instanceof APIError) {
    console.error(`Status ${e.status}: ${e.message}`);
  }
}

The gateway reduces 429s via fallback, but client-side retries with backoff are still sane for production. Use p-retry or a small loop.

Troubleshooting

• 401 Unauthorized – .env not loaded, or key copied with newline.
• 404 Model not found – model ID typo. List models via curl.
• Base URL ignored – you imported openai from openai (the official SDK) instead of @ai-sdk/openai. The AI SDK provider is a different package.
• Stream hangs – forgot for await on textStream, or process exited before flush.

Minimal production pattern

Keep the provider factory isolated:

// src/ai.ts
import { openai } from '@ai-sdk/openai';

export const n4n = openai({
  baseURL: process.env.N4N_BASE_URL!,
  apiKey: process.env.N4N_API_KEY!,
});

export const chatModel = n4n(process.env.N4N_DEFAULT_MODEL ?? 'openai/gpt-4o');

This gives you one place to swap routing headers, add cache hints, or change the default model. The rest of your app imports chatModel and calls generateText or streamText without caring which provider ultimately answers.