zihin

n8n nodes for Zihin AI - Chat Model with Tool Calling, Image Analysis, Audio Transcription, Document Parsing

Package Information

Released: this month
Downloads: 279 weekly / 320 monthly
Latest Version: 0.10.1
Author: Zihin AI Inc.

Available Nodes

Zihin Agent icon
Zihin Agent
Invoke a Zihin agent (runs the full agent loop: tools, memory, governance)
Zihin Chat Model (Deprecated) icon
Zihin Chat Model (Deprecated)
[Deprecated — use the Zihin Agent node] Chat Model for the Zihin LLM gateway with provider routing and Tool Calling
Zihin icon
Zihin
Process media with Zihin AI - Image Analysis, Audio Transcription, Document Parsing

Documentation

n8n-nodes-zihin

npm version
License: MIT

n8n community nodes for Zihin AI - Unified LLM API with intelligent provider routing, Tool Calling support, and Media Processing (Image Analysis, Audio Transcription, Document Parsing).

Nodes Included

Node Type Description
Zihin Agent ⭐ App Node Recommended. Invoke a hosted Zihin agent (runs the full agent loop: tools, memory, governance)
Zihin Chat Model (deprecated) AI Sub-node LangChain Chat Model — direct LLM gateway. Superseded by Zihin Agent.
Zihin App Node Media Processing: Image, Audio, Document

Zihin Agent is the recommended way to reach Zihin: every external request runs through an agent
under your tenant's RBAC, quota, HITL and audit.

⚠️ Zihin Chat Model is deprecated (as of 0.7.0). It calls the direct LLM gateway
(/api/v3/llm/public/call), which runs outside governance. Migrate to the Zihin Agent node.
Removal is planned for v1.0.0.

Installation

Via n8n Community Nodes (Recommended)

  1. Go to Settings > Community Nodes > Install
  2. Search for n8n-nodes-zihin and install

Via npm

npm install n8n-nodes-zihin

Configuration

  1. Get your API Key at zihin.ai > Settings > API Keys
  2. In n8n: Credentials > Add Credential > Zihin API
  3. Enter your API Key (format: zhn_live_xxx)

Zihin Agent — output

Field Meaning
content The agent's final answer
contentSource response = the final event (safe to publish). tokens = the stream ended early and this is the raw per-iteration text, including the model's internal deliberation — branch on this before sending anywhere external
sessionId Reuse on the next call to continue the conversation
blocks Structured cards emitted by the agent, if any
usage, model, iterations, executionTimeMs Cost and timing from the backend
sources References the agent used (now populated; used to be always empty)
outcome, finishReason, truncated, executionId How the turn ended (COMPLETED, LENGTH…) and its ID for support
gated true when the reply is a canned gate message (human handoff, denylist): no model ran
acceptedFields, ignoredFields What the server applied from Structured Input. ignoredFields with reason redacted is a warning: a Context value looked like a secret and was masked

Zihin Agent — structured input (admin/owner API key)

Field Who sees it Use it for
Consumer Key the platform Who the end user is (e.g. a phone number, digits only): per-person memory and controls. To continue conversations a webhook stored, use the same value
Context (JSON) the model and the tools Data the agent should consider, e.g. {"customer": "Ana", "plan": "pro"}. Stored with the conversation
Bindings (JSON) only the tools Internal IDs and lookup keys. Never shown to the model, never stored
Session From — Field names from Context/Bindings (comma-separated). The same values always continue the same conversation, like a webhook derive

Flat objects only (text, number, boolean): up to 50 fields, 2,000 characters in total for Context
and 16,000 for Bindings. Never put credentials here — use a tenant secret. These fields need an
admin/owner API key; with any other key the node fails with a clear message instead of running the
agent without them.

With Continue On Fail, the error item carries kind (timeout, blocked, config,
quota_exceeded…), retryable, code and the IDs (requestId, executionId, sessionId) so you
can branch on it. A turn that hit the server deadline comes back as kind: timeout with the
sessionId to resume.

Timeout: the value you set is sent to the backend as its own budget, and the node waits a little
longer than that so the backend's own outcome arrives first. Leave it empty to use the default
(200s, above the backend's 180s stream budget). Cancelling the workflow execution now cancels the
agent turn on the backend too — it no longer keeps running and billing after you stop it.

Plan errors (trial expired, no subscription, quota exhausted) surface with a specific message and
are never retried; they are not credential problems.

Zihin Chat Model

Designed for AI Agents with Tool Calling support.

[Chat Trigger] → [AI Agent] ← [Zihin Chat Model]
                     ↑
                 [Tools]

Usage

  1. Add an AI Agent node
  2. Connect Zihin Chat Model as the Chat Model
  3. Add Tools (Calculator, HTTP Request, etc.)
  4. Connect a trigger and execute

Parameters

Parameter Default Description
Model auto LLM model or "Auto" for intelligent routing
Task Type chat_general Task type for auto-routing optimization
Temperature 0.7 Creativity level (0-2)
Max Tokens 4096 Maximum tokens in response

Advanced Options

Parameter Default Description
Timeout 185s Maximum request timeout. The server allows 180s on this route — cutting earlier returns a timeout while the call keeps running and being billed.
Max Retries 2 Retry attempts with exponential backoff
Base URL Override - Alternative URL for staging/local
Allow Localhost false Allow http://localhost (dev only)
JSON Output Schema - Force structured JSON output

Supported Models

Models are loaded dynamically from the Zihin API.

Providers: OpenAI, Anthropic, Google, Grok, OpenRouter (DeepSeek, Qwen, Mistral, Llama)

Use Auto for automatic routing based on task type.

Task Types (Auto Mode)

Task Type Value Use Case
General Chat chat_general General conversations
Writing write Content creation
Rewriting rewrite_edit Editing and revision
Extraction extract_structure Extract structured data
Reasoning reasoning_analysis Complex analysis
Code code Programming tasks
Data Query data_query SQL, data queries
Research research Investigation

Zihin (Media Processing)

Process media files with Vision AI, Speech-to-Text, and Document parsing.

Resources & Operations

Resource Operation Description
Image Analyze Vision AI analysis (GPT-4o, Claude)
Audio Transcribe Speech-to-text (Whisper)
Document Parse Extract content (PDF, Excel, CSV, DOCX)

Image Analysis

Field Required Description
Image Yes URL or base64 data URI
Prompt No Analysis instructions
Extract Text No Enable OCR mode
Detail No low, high, auto
Provider No auto, openai, anthropic

Audio Transcription

Field Required Description
Audio Yes URL or base64 data URI
Language No ISO code (pt, en, es...)
Include Timestamps No Add segment timestamps
Prompt Hint No Context for better accuracy

Supported formats: mp3, wav, ogg, flac, m4a, webm, mp4

Timeout (all media operations): leave it at 0 (automatic). The node then waits just above the
server's own limit for each operation: 395s for transcription, 185s for image analysis and document
parsing. A lower value aborts work the server is still processing and billing. Workflows created
before 0.10.0 saved 120000 in this option: remove it to get the automatic value. The timeout covers
the whole request, and cancelling the workflow execution cancels the media request too.

Document Parsing

Field Required Description
Document Yes URL or base64 data URI
File Type No auto, pdf, xlsx, csv, docx
Extract Mode No text, tables, all
Sheet Name No Excel sheet name
Max Pages No PDF page limit

URL Tips

For Google Drive files, convert share links to direct download:

# Share link (won't work)
https://drive.google.com/file/d/FILE_ID/view?usp=sharing

# Direct download (works)
https://drive.google.com/uc?export=download&id=FILE_ID

Troubleshooting

Error Solution
"Invalid API Key" Verify the key in Zihin dashboard
"Invalid base URL" Enable "Allow Custom Base URL"
"Timeout" Increase timeout in Options
"Invalid file format" Check supported formats

Security

Protections

  • SSRF Prevention: URL validation, private IPs blocked, HTTPS-only
  • Payload Limits: Configurable size limits
  • Error Sanitization: Sensitive data removed from errors
  • Telemetry Privacy: IDs are hashed

Best Practices

  • Keep n8n updated (>=1.120.4)
  • Use RBAC to restrict workflow editing
  • Enable MFA for n8n access
  • Rotate API keys periodically

Credential Format

  • Production: zhn_live_xxx
  • Test: zhn_test_xxx

Changelog

v0.6.0 (2025-02-03)

  • New Node: Zihin - Media Processing (Image, Audio, Document)
  • Image Analysis: Vision AI with GPT-4o and Claude
  • Audio Transcription: Whisper with timestamps
  • Document Parsing: PDF, Excel, CSV, DOCX support
  • Structured Output: JSON Schema support for Chat Model
  • Allow Localhost: Development mode option

v0.5.0 (2025-01-14)

  • Security Hardening: SSRF prevention, payload limits
  • @langchain/core >=0.3.80: Serialization fix

v0.4.0 (2025-12-24)

  • Dynamic Models: Loaded from API
  • Task Types: 8 types for auto-routing

v0.3.0 (2025-12-16)

  • Timeout, retries, base URL override

v0.2.0 (2024-12-05)

  • Chat Model with Tool Calling

v0.1.0

  • Initial release

Links

License: MIT | Developed by Zihin AI Inc

Discussion