n8n-nodes-tpg-ai-hub

An n8n community node for the Orlop AI Hub (formerly the TPG AI Hub) — The Platform
Group / Orlop AI Platform API.

This package adds a single Orlop AI Hub node and an Orlop AI Hub API credential to
your n8n instance, exposing the core Orlop AI Hub operations across AI generation, images,
video, leads, knowledge graph, SEO, and more. It follows n8n's community-node conventions,
so it installs from Settings → Community Nodes by entering only the package name.

Note on naming: the npm package name (n8n-nodes-tpg-ai-hub) and the internal node/
credential type names (tpgAiHub / tpgAiHubApi) are unchanged from the TPG AI Hub era.
Renaming them would break every existing workflow and credential that references this
node, so only the user-visible display names and text were rebranded to Orlop AI Hub. See
the migration notes linked from this repo's issue tracker for the full rationale.

Installation

Community Nodes (recommended)

For n8n versions that support community nodes (n8n 0.187+), an administrator can install
this package directly from the editor:

1. Open n8n and go to Settings → Community Nodes.
2. Click Install.
3. Enter the package name n8n-nodes-tpg-ai-hub.
4. Check I understand the risks of installing unverified code from a public source.
5. Click Install.

After installation, the Orlop AI Hub node and the Orlop AI Hub API credential become
available in the workflow editor.

Installing community nodes requires an n8n instance where community node installation is
enabled. On managed/cloud plans this may be restricted by your plan or administrator.

Manual installation (self-hosted)

For self-hosted setups you can install the package into your n8n installation directory
(the folder containing your n8n node_modules, typically ~/.n8n):

npm install n8n-nodes-tpg-ai-hub

Restart n8n after installing so the new node and credential are loaded.

Credentials

The node authenticates with an Orlop AI Hub API credential. Create one from the node's
credential dropdown or from Credentials → New:

• Hub Domain / Base URL — which Hub backend to call. A dropdown with three options:
  Legacy TPG AI Hub (https://api.the-platform-group.ai, the default),
  Orlop AI Hub (https://api.orlop-tech.com), and Custom (reveals a free-text
  Custom Base URL field, e.g. for http://localhost:8080 in local development).
  Orlop and Legacy are currently separate backends with separate API keys, so pick
  whichever one your API key was issued for. Credentials created before this option
  existed keep working unchanged: the default stays the legacy host because n8n does not
  store default values, and a custom URL you typed earlier is preserved as-is.
• API Key — your Orlop AI Hub API key. Stored as a masked password value and sent as a
  Bearer token (Authorization: Bearer <apiKey>) on every request.

There is no authentication-type selector: the Orlop AI Hub accepts only Bearer authentication,
so the API key is always sent as a Bearer token for all operations.

When you save the credential, n8n runs a credential test that issues
GET /v1/models against the configured base URL using your API key. A 200 response
confirms the credential works.

Operations

Select the operation on the node. Each operation maps to a fixed Orlop AI Hub endpoint and
exposes friendly inputs tailored to that operation. The Model field is a dropdown
loaded live from the API (GET /v1/models). Optional fields left empty are omitted from
the request, and Bearer authentication is required and used for every operation.

1. Agent Chat — POST /agent/chat

Calls the Orlop AI Hub agent with tool discovery.

Field	Description
Model	Model dropdown loaded from the API.
Messages	Message builder: add rows of Role (User/Assistant/System) and Content. Rows with empty content are skipped.
Attachments	Image/file builder (see Attachments below): each row is attached to your latest user message as a vision/file content part.
Advanced	Optional power-user JSON fields: Config, Webhooks, MCP Config (only sent when added).

2. Generate — POST /generate

Multi-modal generation that can produce text or image output, including batch and
structured outputs.

Field	Description
Mode	text or image. Defaults to text.
Model	Model dropdown loaded from the API.
Prompt	Generation prompt. Ignored when a Messages list is supplied in Options.
Attachments	Image/file builder (see Attachments below): each row is attached alongside your prompt as a vision/file content part.
Aspect Ratio	Output aspect ratio (image mode).
Options	Advanced tuning, only sent when added: Temperature, Max Tokens, Response Format (Text/JSON), JSON Schema, Stream, Messages builder, Batch (JSON). Temperature, Max Tokens, Response Format and JSON Schema are sent inside the request config object.

Structured Output (JSON)

The Generate operation can return structured JSON validated against a schema you
define:

1. Open Options and add Response Format, then set it to JSON
   (application/json).

2. Add JSON Schema. It is pre-filled with a ready-to-edit template:

   {
     "type": "object",
     "properties": {
       "title": { "type": "string" },
       "summary": { "type": "string" },
       "tags": { "type": "array", "items": { "type": "string" } }
     },
     "required": ["title"]
   }
   

   Edit the template to match the shape you want back.

The model returns JSON that conforms to your schema. The structured output
arrives as a JSON string in the response text; with Simplify Output enabled
(the default) the node also parses it into a json field for easy downstream
use. If you clear the JSON Schema field entirely, no schema is sent.

Output options

Two top-level toggles control how each operation's response is emitted:

• Simplify Output (default on, all operations) — returns a cleaned,
  easy-to-use result instead of the full raw API response. The large
  account-wide usage noise is removed, and just the useful fields are surfaced:
  text / json / image and model / usage for Generate and Agent Chat,
  images for Image Edit, image for Virtual Try-On, and a models list for
  List Models. Turn it off to receive the raw API response unchanged.
• Return Images as Binary (default off, Generate / Image Edit / Virtual
  Try-On) — attaches generated or edited images as binary data on the item
  (keys data, data1, data2, …) instead of inlining their base64 in JSON.
  Recommended when saving images to disk or sending them on to another node.
  The base64 strings are removed from the JSON payload to keep it small.

Attachments (images & files)

The Attachments builder on Agent Chat and Generate, and the Images / Product
Images builders on Image Edit and Virtual Try-On, all support the same three ways to
provide a file:

• URL — a publicly reachable link to the file.
• Base64 — inline base64-encoded data plus a MIME Type.
• Binary Data — reads a binary property already on the item (e.g. from Read/Write
  Files from Disk, an HTTP Request node, or a webhook file upload) via its Input
  Binary Field name (defaults to data), base64-encoding it automatically. This is the
  way to attach a file produced by an earlier node without a manual conversion step.

On Agent Chat and Generate, each row also has an Attachment Type: Image (default) or
File (e.g. PDF). The underlying API distinguishes vision images from non-image files
(such as PDFs) at the content-part level (type: "image" vs. type: "file"), so set
Attachment Type to File when attaching a PDF or other document — sending it as an
Image part is not guaranteed to be understood by the model. Image Edit and Virtual
Try-On are image-only endpoints and have no Attachment Type (every row is an image).

3. Image Edit — POST /ai-images-editor

Edits images using Gemini image models.

Field	Description
Images	Image builder (see Attachments above): each row is a URL, inline Base64, or Binary Data source.
Instructions	List of edit instructions (one per row).
Pro Mode	Enable higher-quality processing.
Resolution	One of 512, 1K, 2K, 4K. Defaults to 2K.
Aspect Ratio	Output aspect ratio.

4. Virtual Try-On — POST /virtual-try-on

Generates images of products worn by people or placed in styled scenes.

Field	Description
Product Images	Image builder (see Attachments above): each row is a URL, inline Base64, or Binary Data source.
Context	Scene context description.
View Mode	Camera view mode (e.g. wide, closeup, dynamic).
Aspect Ratio	Output aspect ratio.
Resolution	One of 1K, 2K, 4K.
Is Edit Mode	Treat the request as an edit of an existing result.
Negative Prompt	Elements to avoid in the output.
Advanced	Optional person-image and Photographer Mode fields, only sent when added: Person Image Base64, Person MIME Type, Reference Subject, Camera Setup, Material Details, Light Architecture, Environment Styling.

5. Chat Completions (OpenAI-Compatible) — POST /v1/chat/completions

A drop-in replacement for the OpenAI Chat Completions API — usable with OpenAI SDKs, Kilo
Code, and Codex (wire_api "chat"). Unlike Agent Chat/Generate's friendly Messages builder,
Messages here is raw JSON in OpenAI's own wire format, since this endpoint is meant to
carry through whatever an SDK or upstream node already produced.

Field	Description
Model	Model dropdown loaded from the API (Gemini/Claude/Nova IDs are routed accordingly). Required.
Messages	Raw JSON array of OpenAI-format message objects. Required.
Options	Only sent when added: Max Tokens, Stream, Temperature, Tools (JSON), Tool Choice (JSON).

6. Messages (Anthropic-Compatible) — POST /v1/messages

A drop-in replacement for the Anthropic Messages API — usable with Claude Code
(ANTHROPIC_BASE_URL) and Anthropic SDKs. As with Chat Completions, Messages is raw
JSON in Anthropic's own wire format.

Field	Description
Model	Model dropdown loaded from the API. Required.
Messages	Raw JSON array of Anthropic-format message objects. Required.
Max Tokens	The maximum number of tokens to generate. Required.
Options	Only sent when added: System (JSON string or array of content blocks), Stream, Tools (JSON), Tool Choice (JSON).

7. Count Tokens (Anthropic-Compatible) — POST /v1/messages/count_tokens

Returns an input token estimate for a Messages-shaped request, without generating a
response.

Field	Description
Model	Model dropdown loaded from the API.
Messages	Raw JSON array of Anthropic-format message objects.
Options	Only sent when added: System (JSON), Tools (JSON).

8. List Models — GET /v1/models

Retrieves the available models. This operation takes no input fields.

9. Changelog: Get RSS Feed — GET /changelog/rss

Returns the latest Orlop AI Hub updates as an RSS feed. The XML document is returned under
an rss field. No input fields.

10. Conversations — /conversations

Manage saved Agent Chat conversation history.

• Conversations: List or Get (GET /conversations) — leave Conversation ID empty to
  list the 50 most recent conversations, or set it to fetch a single one.
• Conversations: Save (POST /conversations) — create or update a conversation by
  Conversation ID (required), using the same Messages builder as Agent Chat, plus
  optional Title, Description, and Agent ID (in Options).
• Conversations: Delete (DELETE /conversations) — permanently deletes the conversation
  by Conversation ID (required).

11. Leads: Discover and Analyze — POST /scraper/analyze

Lead acquisition pipeline (search or pre-supplied list), optional Lusha enrichment, and AI
analysis.

Field	Description
Query	Natural-language search query (skipped when a Leads list is provided).
Leads	List builder of pre-defined companies (Name, Website).
Enrich via Lusha	Use Lusha to find websites for the leads.
Goal and Offer	Sales goal/offer (enables detailed AI processing).
Sender Context	Sender bio/context.
Limit	Max leads to process (default 2).
Search Mode	places or serp.

12. Live Token: Mint Ephemeral Token — POST /live-token

Mints a single-use, short-lived ephemeral token (plus the configured native-audio Live API
model) for connecting a browser directly to the Gemini Live API for real-time voice
conversations, without exposing server credentials. This operation takes no input fields.

13. Video: Generate / Get Status / List — /ai-videos*

• Video: Generate (POST /ai-videos/generate) — text-to-video (8s). Fields: Prompt,
  Aspect Ratio (16:9 / 9:16), Resolution (720p / 1080p), Enhance (run the prompt
  enhancer first). With Wait Until Complete enabled (default), the node polls the status
  endpoint until the video finishes (up to Max Wait Seconds) and returns the final result
  with a ready-to-use video URL. Limited to 3 videos per user per day.
• Video: Get Status (GET /ai-videos/status) — poll a video by Video ID; returns its
  status and, when complete, an absolute video URL.
• Video: List (GET /ai-videos) — the latest videos plus today's remaining quota.

Relative video URLs returned by the API are converted to absolute URLs automatically.

14. Knowledge Graph — /knowledge-graph*

• Knowledge Graph: List Graphs (GET /knowledge-graphs) — list available graphs.
• Knowledge Graph: Process (POST /knowledge-graph/process) — extract entities from a
  Messages list into a graph (optional Graph ID, defaults to main).
• Knowledge Graph: Query (POST /knowledge-graph/query) — search a graph by Query
  (optional Graph ID).
• Knowledge Graph: Update Node (POST /knowledge-graph/update) — edit a node's
  description by Node ID.
• Knowledge Graph: Delete Node (DELETE /knowledge-graph/delete) — permanently deletes a
  node (fact or entity) by Node ID.

15. SEO — /seo/*

• SEO: Analyze Topic (POST /seo/analyze-topic) — analyze a Topic (intents, gaps,
  competition).
• SEO: Generate Subtopics (POST /seo/generate-subtopics) — generate subtopics for a
  Topic (optional Topic ID).
• SEO: Generate Output (POST /seo/generate-output) — generate semantic HTML. Takes the
  Topic object from Analyze Topic and the Subtopics array from Generate Subtopics
  (at least 4 required) plus optional Content Settings. Use expressions to pass the prior
  steps' output, e.g. {{ $json.topic }} and {{ $json.subTopics }}.
• SEO: Refine Output (POST /seo/refine-output) — apply a free-text Refinement to an
  existing HTML Output.

Not yet supported: the Image Resizer (/image-resizer) endpoint is intentionally
excluded. The API gateway currently rejects file and CSV uploads to that route (multipart
and text/csv bodies are not forwarded), so it cannot be driven reliably from the node yet.
The API documentation now specifies the target multipart/form-data (files) and text/csv
(batch) request contract for this endpoint, but the gateway restriction has not yet been
confirmed as lifted — it will be added once that's verified.

Development

# Install dependencies
npm install

# Build (TypeScript compile + copy icons into dist)
npm run build

# Lint
npm run lint

# Run tests
npm test

Windows note: if npm install fails while building the isolated-vm native
dependency, run npm install --ignore-scripts. The package only needs n8n-workflow
as a build-time, types-only peer dependency, so skipping native build scripts does not
affect building or publishing this node.

Publishing

Maintainer flow for releasing to the public npm registry:

# 1. Authenticate with your npm account
npm login

# 2. Bump the version
npm version patch   # or: minor | major

# 3. Publish
npm publish

The prepublishOnly script runs the build and publish-time lint automatically before the
package is published, and only the dist directory is shipped (as declared by the files
field in package.json). After publishing, verify the install in n8n via
Settings → Community Nodes by entering n8n-nodes-tpg-ai-hub (the npm package name is
unchanged — see the naming note near the top of this README).

License

MIT © The Platform Group GmbH & Co. KG

Author: Fabian Stamminger ai@the-platform-group.com