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¶
- Create a workflow with a Manual Trigger.
- Add an AI Agent node (or a Basic LLM Chain) and give it a Chat Model: OpenAI Chat Model with the credential above.
- In Model, pick a model From List, or choose ID and type a name your organisation has approved, for
example
gpt-4o-mini. - 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).
- 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-Afterheader; 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.