Skip to content

n8n

Your n8n workflows keep their AI nodes as they are. Change the address on one credential and every model call they make is checked against your policies, charged to the right team and recorded in Request logs, and the same nodes can reach Claude or Gemini as well as OpenAI's models.

What it is

n8n is a workflow automation tool, self-hosted or n8n Cloud. Its OpenAI and Anthropic credentials both have a Base URL field, so the OpenAI node, the OpenAI Chat Model and Anthropic Chat Model sub-nodes, and the AI Agent and chain nodes that use them can all send their calls to the gateway.

The two settings

In n8n, open Credentials, create a new credential (or edit the one your workflows use) and fill in:

Credential Field Value
OpenAI Base URL https://<your-gateway>/v1
API Key Your Vidai key (starts vk_), never a provider's key
Organization ID (optional) Leave empty
Anthropic Base URL https://<your-gateway> (no /v1: n8n adds it)
API Key Your Vidai key

The OpenAI credential sends the key as Authorization: Bearer, the Anthropic credential as x-api-key; the gateway accepts both. The gateway's address, and the base URL for each kind of client, are under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

When you save, n8n tests the credential by listing models; the gateway answers that itself, so a green test means the address and the key are right.

A minimal call

  1. Create a workflow with a Manual Trigger.
  2. Add an AI Agent node (or a Basic LLM Chain) and give it a Chat Model: OpenAI Chat Model with the credential above.
  3. In Model, pick a model From List, or choose ID and type a name your organisation has approved, for example gpt-4o-mini.
  4. Switch Use Responses API off: from version 1.3 of the node it's on by default, and Claude and Gemini models need it off (see What goes through the gateway).
  5. Ask for something short, such as "Say hello in Dutch", and choose Execute workflow.

The same OpenAI credential calls Claude or Gemini: type a name such as claude-sonnet-4.5 in Model. The gateway translates the request for that provider and the answer back into the OpenAI shape n8n reads. The Anthropic credential works the other way round: the Anthropic Chat Model can call gpt-4o-mini or gemini-3.5-flash in the same way.

Streaming

When an AI Agent streams its answer to a chat trigger or webhook, the stream comes from the gateway in the format the node expects, whichever provider answered. Nothing to set.

Tool calls

An AI Agent decides which of its tools to call through the model, and those calls (and every reasoning step) go through the gateway. The tools themselves (an HTTP Request, a Code node, a calculator) run inside n8n, not through the gateway. In Request logs, the Tool filter under More filters finds the calls that offered or called a tool by its name.

Reading what the gateway did

The AI nodes don't show response headers. Find the call in Request logs instead: filter by Key or Model under More filters. Each call shows the model that answered, its cost, and which policy or rule acted on it.

If you need the headers in a workflow, call the gateway with an HTTP Request node (URL https://<your-gateway>/v1/chat/completions, an Authorization: Bearer vk_… header and a JSON body) and switch on Include Response Headers and Status under Options › Response. x-vidai-request-id is the call's reference: paste it into Request logs › Request reference. x-vidai-model says which model answered.

Errors

When the gateway refuses a call, the node fails with the status and the message. The common ones:

Status Gateway code What to do
401 invalid_api_key, missing_api_key Check the API Key on the credential
403 model_not_allowed, denied_by_routing_rule Use a model your key may call, or ask an admin
403 content_guardrail_blocked A guardrail stopped the content; change the prompt
404 model_not_found Check the model name on Models
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded Slow down; use n8n's Retry On Fail with a wait

The node's error output has the message; the code is in the x-vidai-error-code header, which you see with an HTTP Request node, and on the call in Request logs.

Model names

Use the names your organisation has approved, as listed under Models in the Control room. With the gateway as the Base URL, the From List option shows exactly the models your key may call. An alias set by an admin works like any other name.

What goes through the gateway

In n8n Through the gateway
OpenAI Chat Model with Use Responses API off, in an AI Agent or chain Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models
Anthropic Chat Model Yes, to the same providers
OpenAI Chat Model with Use Responses API on (the default from node version 1.3), and its Built-in Tools To OpenAI and Azure OpenAI models only; another provider gets a clear 400
OpenAI node (version 2): text messages, images, audio To OpenAI and Azure OpenAI models only: its text operations use the Responses API
OpenAI node: assistants No: the gateway doesn't carry the Assistants API
Other AI nodes (Google Gemini, Mistral, Ollama…) with their own credentials No: they call their provider directly. Use the OpenAI or Anthropic credential instead

To reach Claude or Gemini from a plain step (no agent), use a Basic LLM Chain with the OpenAI Chat Model or the Anthropic Chat Model, rather than the OpenAI node.

Check it works in a minute

Save the credential (the test lists models through the gateway), then run the minimal workflow above. A short answer means the address and key are right. The call shows in Request logs within seconds.

Good to know

  • On n8n Cloud the gateway must be reachable from the internet; a self-hosted n8n needs to reach it on your network.
  • One key per workflow, or per team of workflows, keeps their spend apart: what the key acts for decides who pays.
  • OpenAI Chat Model retries on its own (Max Retries under its options). A fallback chain may already have tried another model before you see an error; lower the retries if you don't want both.
  • The gateway's own 429 has no Retry-After header; set a wait between tries on your side.
  • The OpenAI credential's Add Custom Header can add a header such as x-request-id, which is kept with the call.