Skip to content

Use CloudService in n8n

Run Claude, Codex, and DeepSeek models in n8n's AI Agent through one OpenAI-compatible credential — plus a starter workflow you can import.

Attach the model as the AI Agent's “OpenAI Chat Model” sub-node. Do not use the standalone “OpenAI” node with a CloudService key: its current version has a known custom-base-URL bug (n8n issue #21651) where the credential test passes and every real request then fails with a 404 at runtime.

The recipe

Works on n8n Cloud and any self-hosted n8n 1.x with the AI nodes available.

  1. Add an AI Agent node. n8n inserts the Chat Trigger (“When chat message received”) automatically; keep that wiring.
  2. Click the agent's Chat Model socket and choose OpenAI Chat Model.
  3. In the model node, open Credential to connect with → Create new credential, name it CloudService API, and fill exactly two fields:
    • API Key: your full CloudService key
    • Base URL: https://api.yourdomain.example/v1 for an API-credit key, or https://api.yourdomain.example/token/v1 for a token-pack key — the two are not interchangeable. Leave Organization ID empty.
  4. Switch the Model selector from From list to By ID and enter one exact model id, for example gpt-5.4-mini.
  5. Open the chat panel and send a message.

Three setup mistakes to avoid

1. The wrong OpenAI node

n8n has two ways to call an OpenAI-compatible API, and only one of them respects a custom base URL reliably. The OpenAI Chat Model sub-node under the AI Agent (or under a Basic LLM Chain) sends standard Chat Completions and works with CloudService. The standalone OpenAI node (“Message a model”) is the one affected by the n8n issue #21651 regression: it 404s at runtime against custom gateways even after its credential check succeeds. If a workflow passes the credential test but every execution fails, check which node you used before anything else.

2. The wrong base URL

The credential's Base URL must end at the version segment — n8n appends the request path itself:

  • Correct (API credit): https://api.yourdomain.example/v1
  • Correct (token packs): https://api.yourdomain.example/token/v1
  • Wrong: …/v1/chat/completions — the path gets doubled on every call
  • Wrong: …/v1/v1 — a doubled version segment from pasting /v1 onto a URL that already has it

A valid key used on the wrong surface — a token-pack key against the credit /v1, or a credit key against /token/v1 — comes back as a generic 401 Invalid API key. The key is not dead; it is on the wrong base URL. Match the URL to your key type — check which you have on Authentication & key type.

3. The empty model dropdown

The From list dropdown reflects whatever your key can call. Current n8n lists every model a custom gateway returns; older versions filtered the list client-side and could hide CloudService ids. Either way By ID is the reliable choice — type an exact id:

  • gpt-5.4-mini
  • gpt-5.6-sol
  • claude-opus-5
  • claude-sonnet-5
  • claude-haiku-4-5-20251001

Use only ids returned by your key's authenticated catalog — see Models and Authentication & key type.

Claude in the same node

There is no Anthropic node to configure. Enter a claude-* id (for example claude-opus-5) in the same OpenAI Chat Model sub-node: CloudService translates OpenAI-compatible chat calls to the Anthropic upstream on the gateway side. This is also how a Claude-only key works in n8n — same credential form, same base URL rule, Claude model ids only.

DeepSeek V4 Flash

deepseek-v4-flash and glm-5.2 work through the same credential, but each needs a key scoped to that exact model — on any other key the request is rejected with a 403. Both support tool calling in the AI Agent node.

Two things worth setting explicitly on these models, because both are reasoning models and n8n leaves them unset by default:

  • Maximum Number of Tokens. n8n sends no limit unless you set one. Reasoning tokens are spent from the same completion budget as the answer, so a long structured response can run out of room and come back truncated — n8n reports that as “Model output doesn’t fit required format”. Set it to a few thousand for agent workflows.
  • Structured Output Parser. If you attach one, keep the schema small and the prompt explicit. A reasoning model that thinks at length before answering has less budget left for the JSON itself.

Starter workflow: import and run

Download cloudservice-n8n-starter.json or copy the block below. It is a minimal Chat Trigger → AI Agent → OpenAI Chat Model workflow with the model set to gpt-5.4-mini.

  1. In n8n, open Workflow → Import from File… — or copy the JSON and paste it straight onto the canvas with Ctrl+V / Cmd+V.
  2. Open the OpenAI Chat Model node. It references a credential named CloudService API that does not exist on your instance yet — create it there with your key and base URL, exactly as in the recipe above.
  3. Open the chat panel and send Reply with exactly OK. A short answer confirms the key, URL, and model id in one round trip.
cloudservice-n8n-starter.json
{
  "name": "CloudService chat starter",
  "nodes": [
    {
      "parameters": {
        "options": {}
      },
      "id": "81a4277f-068f-4e25-95d6-0c35e9fe2202",
      "name": "When chat message received",
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "typeVersion": 1.1,
      "position": [
        0,
        0
      ],
      "webhookId": "83a13d6a-e9e6-4955-8d15-72f36a6b6a37"
    },
    {
      "parameters": {
        "options": {}
      },
      "id": "25811587-54ec-466b-824d-ff9ffb216116",
      "name": "AI Agent",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "typeVersion": 1.7,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "model": {
          "__rl": true,
          "value": "gpt-5.4-mini",
          "mode": "id"
        },
        "options": {}
      },
      "id": "f097ebef-1c9d-4480-86bf-ca536d991f14",
      "name": "OpenAI Chat Model",
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
      "typeVersion": 1.2,
      "position": [
        200,
        220
      ],
      "credentials": {
        "openAiApi": {
          "id": "cloudservice-api-credential",
          "name": "CloudService API"
        }
      }
    }
  ],
  "connections": {
    "When chat message received": {
      "main": [
        [
          {
            "node": "AI Agent",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "OpenAI Chat Model": {
      "ai_languageModel": [
        [
          {
            "node": "AI Agent",
            "type": "ai_languageModel",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false,
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  },
  "meta": {
    "templateCredsSetupCompleted": false
  }
}

Fallback: the HTTP Request node

If you want raw API responses, are running DeepSeek without an agent, or the AI nodes are unavailable on your instance, call the endpoint directly:

  • Method: POST
  • URL: https://api.yourdomain.example/v1/chat/completions (token-pack keys: https://api.yourdomain.example/token/v1/chat/completions)
  • Authentication: Generic Credential Type → Header Auth, with Name Authorization and Value Bearer ak_live_... — the word Bearer, one space, then the key
  • Send Body: on, as JSON:
request-body.json
{
  "model": "gpt-5.4-mini",
  "messages": [{ "role": "user", "content": "Reply with exactly OK" }],
  "max_tokens": 16
}

A Header Auth credential keeps the key inside n8n's credential store, so it never appears in a shared or exported workflow.

Verify it works

Run the same request from a terminal to separate key problems from n8n problems:

verify.sh
export CLOUDSERVICE_API_KEY="ak_live_..."

curl "https://api.yourdomain.example/v1/chat/completions" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role":"user","content":"Reply with exactly OK"}],
    "max_tokens": 16
  }'

A JSON response whose message content is OK proves the key, URL, and model. If this curl succeeds but n8n fails, the fault is in the node choice or credential fields above — not the key. If the curl itself fails, start with Error Codes.

Workflow exports never contain the key: n8n stores credentials separately, and the JSON references them by name and id — never the secret. Keep it that way — put the key in the OpenAI or Header Auth credential, never inline in a node field, and never reuse one key across the credit and token-pack URLs.