Description

n8n-nodes-custom-ia

This is an n8n community node package with two nodes that work with any OpenAI-compatible AI provider:

• Custom AI Chat Model — a Chat Model sub-node for the AI Agent, Basic LLM Chain and any other AI node that accepts a Chat Model.
• Custom AI Media — an action node that transcribes audio (/audio/transcriptions, /audio/translate) and analyzes images (vision via /chat/completions).

Configure a custom Base URL, API key and optional custom headers once in the credentials, and use them from both nodes.

Supported providers include (but are not limited to):

• OpenAI (https://api.openai.com/v1)
• DeepSeek (https://api.deepseek.com)
• OpenRouter (https://openrouter.ai/api/v1)
• Groq (https://api.groq.com/openai/v1)
• Mistral (https://api.mistral.ai/v1)
• xAI / Grok (https://api.x.ai/v1)
• Ollama (http://localhost:11434/v1)
• LM Studio (http://localhost:1234/v1)
• Any other service exposing an OpenAI-compatible /chat/completions API

n8n is a fair-code licensed workflow automation platform.

Installation
Credentials
Custom AI Chat Model
Custom AI Media
Compatibility
Usage
Resources
Version history

Installation

Follow the installation guide in the n8n community nodes documentation.

In short, on a self-hosted instance:

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter n8n-nodes-custom-ia and confirm.

Credentials

The Custom AI API credential has the following fields:

| Field | Description |
| — | — |
| API Key | Sent as Authorization: Bearer . Leave empty for providers that don’t require authentication (e.g. local servers). |
| Base URL | Base URL of the OpenAI-compatible API, including the version path when the provider uses one (e.g. https://api.openai.com/v1). The nodes call /chat/completions, /audio/transcriptions and /models. |
| Add Custom Header | Optional. Adds one extra header to every request (for example HTTP-Referer or X-Title required by some gateways). |
| Header Name / Header Value | Name and value of the custom header. |

When you save the credential, n8n tests it by calling /models with the configured authentication.

> Note: If your provider doesn’t expose /models (for example a transcription-only server), n8n reports the credential test as failed when saving. The credential still works for transcription: you can ignore that message.

Provider examples

| Provider | Base URL | API key required |
| — | — | — |
| OpenAI | https://api.openai.com/v1 | Yes |
| DeepSeek | https://api.deepseek.com | Yes |
| OpenRouter | https://openrouter.ai/api/v1 | Yes |
| Groq | https://api.groq.com/openai/v1 | Yes |
| Mistral | https://api.mistral.ai/v1 | Yes |
| xAI (Grok) | https://api.x.ai/v1 | Yes |
| Ollama | http://localhost:11434/v1 | No |
| LM Studio | http://localhost:1234/v1 | No |

Audio and image support per provider (verified)

• Groq (free tier) — recommended for audio: https://api.groq.com/openai/v1 exposes both POST /audio/transcriptions and POST /audio/translate. Free plan: ~2,000 requests/day and 7,200 audio seconds/hour with whisper-large-v3 / whisper-large-v3-turbo. No credit card required.
• OpenCode Zen (https://opencode.ai/zen/go/v1) — images work through chat/completions, but audio does not: /audio/transcriptions returns 404. Use Groq, OpenAI or a local whisper server for the audio resource.
• Chat Trigger file uploads land in the binary property data0 — set the node’s Binary Property to data0.

Custom AI Chat Model

This node is a Chat Model sub-node. It does not execute on its own: connect it to the model input of a root AI node, such as:

• AI Agent
• Basic LLM Chain
• Other chains that accept a Chat Model

Node parameters:

• Model: choose a model from the provider’s /models endpoint or set the model ID manually.
• Options: temperature, maximum number of tokens, top P, frequency/presence penalty, response format (text or JSON), timeout, max retries, “Use Responses API” (OpenAI only), Thinking Mode, Reasoning Effort and Extra Body for provider-specific request parameters as JSON.

Extra Body is merged into the request body last, so it can intentionally override any of the options above or the effective model/stream parameters. Do not put credentials in the Base URL: use the API Key and custom header fields, which are stored encrypted.

Thinking and reasoning

Models that support thinking/reasoning can be controlled with two options:

• Thinking Mode: Default, Enabled or Disabled. Sent as {"thinking":{"type":"enabled"|"disabled"}} (DeepSeek).
• Reasoning Effort: Default, None, Minimal, Low, Medium, High or Max. Sent as reasoning_effort on Chat Completions, or as reasoning.effort when using the Responses API. When Thinking Mode is Disabled, no effort value is sent.

DeepSeek notes:

• Current models are deepseek-v4-flash and deepseek-v4-pro (thinking enabled by default; deepseek-chat and deepseek-reasoner are deprecated aliases).
• DeepSeek accepts low, high and max (medium maps to high).
• In thinking mode, temperature, top P and penalties have no effect.

Custom AI Media

Action node that sends media from the input item to any OpenAI-compatible provider.

| Resource | Operation | Endpoint |
| — | — | — |
| Audio | Transcribe | POST /audio/transcriptions |
| Audio | Translate (to English) | POST /audio/translate |
| Image | Analyze | POST /chat/completions with image_url content |

Audio

• Binary Property: name of the input binary property containing the audio file (flac, mp3, mp4, m4a, ogg, wav or webm). Watch provider file-size limits (25 MB on OpenAI).
• Model: a transcription model, e.g. whisper-1 (OpenAI), groq/whisper-large-v3 (Groq) or your local whisper model.
• Options (only sent when you add them): Language (ISO 639-1 code such as en or es), Prompt (hint for proper nouns), Response Format (json, text, verbose_json with timestamped segments, srt, vtt), Sampling Temperature, Timeout and Extra Body.
• Simplify (off by default): when enabled it returns text (plus language, duration and segments when the provider returns them). Leave it off to receive the raw provider response — recommended, because models differ in where they place the answer (content vs reasoningcontent; the simplified extractor falls back to reasoningcontent automatically). The input binary is passed through to the output.

Image

• Input Type: Binary (default: a base64 data URL is built from the input item) or URL (one or more comma-separated URLs).
• Model: a vision model, e.g. gpt-4o (OpenAI), a *-vision-preview model (Groq) or a multimodal model served by Ollama/LM Studio.
• Prompt: the question or instruction about the image (default What's in this image?).
• Options: Detail (auto/low/high, OpenAI only — auto is not sent so other providers are unaffected), Maximum Number of Tokens, Timeout and Extra Body (e.g. temperature, response_format).
• Simplify (off by default): returns text with the model’s answer (with automatic fallback to reasoning_content for reasoning models). Leave it off to get the raw chat completion.

Notes

• Audio transcription needs a provider with an /audio/transcriptions-compatible endpoint (OpenAI, Groq, local whisper servers…). Image analysis only needs /chat/completions with vision support.
• Extra Body accepts a JSON object and is merged last (it can override any option above). Unknown keys such as proto, constructor and prototype are ignored.
• The node can also be used as an AI tool; in that case prefer the URL input type for images.

Troubleshooting

• “From list” is greyed out in the Model field: the field is in Expression mode — n8n disables the list mode while the value is an expression. Switch the Fixed / Expression segment back to Fixed and the list loads again (check for a leftover = value in the expression).
• Empty text with Simplify enabled: enable Simplify only after checking the raw response (simplify: false) — reasoning models may put the answer in reasoning_content; the extractor falls back to it automatically, but raw output always shows where the provider placed the answer.

Security

• Credentials are stored encrypted by n8n; the API Key and Header Value fields are masked and never written to workflow JSON, node output or error messages.
• The Base URL makes the n8n server issue requests to that host (SSRF surface): only use Base URLs you trust, and never put credentials in the URL — use the API Key / custom header fields instead.
• Custom header names are validated and reserved headers (Authorization, Host, Content-Length, Content-Type, Transfer-Encoding) are rejected, so a custom header can’t silently override authentication or break the request.
• Image URLs accept only http, https and data:image schemes — file:// and other schemes are blocked (second-order SSRF / local file read).
• Error messages redact user:pass@ credentials embedded in URLs. Secrets placed in the query string are not redacted — don’t put API keys in query parameters.
• Files are buffered in memory before upload (base64 grows ~33%): respect provider size limits (25 MB for audio on OpenAI and similar) for images and audio alike.

Compatibility

• Requires a recent self-hosted n8n version that includes the AI node SDK (peer dependency @n8n/ai-node-sdk).
• Unverified community nodes are not available on n8n Cloud.
• Tested against current n8n 2.x releases.

Usage

Chat model

1. Add an AI Agent (or Basic LLM Chain) node to your workflow.
2. Open the Chat Model connector and select Custom AI Chat Model.
3. Create a Custom AI API credential with your provider’s Base URL and API key.
4. Select a model from the list or type the model ID.
5. Run the workflow.

Media (audio / image)

1. Get a file into the workflow as binary (e.g. Read Binary Files, HTTP Request, Email Trigger…).
2. Add a Custom AI Media node and keep the same Custom AI API credential.
3. Choose Audio → Transcribe (or Image → Analyze), set the model and run the workflow.

Resources

• n8n community nodes documentation
• OpenAI API reference
• OpenAI audio transcription reference

Version history

0.2.0

• New Custom AI Media node: transcribe and translate audio (/audio/transcriptions, /audio/translate) and analyze images (vision via /chat/completions) with any OpenAI-compatible provider, reusing the same Custom AI API credential.
• The media node can also be used as an AI tool.

0.1.2

• Security hardening: sanitized Extra Body keys, redacted URLs in errors, normalized Base URL trailing slash, and a leaner published package.

0.1.1

• Added Thinking Mode and Reasoning Effort options for reasoning models.
• Simplified node icons to a solid purple chat bubble.
• Updated DeepSeek model references to deepseek-v4-flash / deepseek-v4-pro.

0.1.0

• Initial release: OpenAI-compatible Chat Model node with custom Base URL, API key and custom header support.