n8n-nodes-huggingface-space

Run inference on any Hugging Face Gradio Space from n8n — and curate your own
model list without forking the node.

Hugging Face hosts tens of thousands of Spaces — live, hosted demos of open models
for images, video, music, speech, text and more. Almost all of them expose a real
API, but that API is Gradio's own queue + Server-Sent-Events protocol, not plain
REST, so you cannot drive one from an HTTP Request node. This node speaks that
protocol, so any Space becomes a step in your workflow.

Three ways to use it:

• Catalog — pick a category and a model. Each entry is backed by Spaces that were
  probed live, plus fallbacks that are tried in order when the primary is paused,
  crashed, or out of GPU quota. Community Spaces go down constantly; the fallback
  chain is the difference between a workflow that works and one that breaks on a
  Tuesday.
• Catalog Overlay — bring your own Spaces. Prepend private forks, replace a
  model's Space chain, or hide models you do not want in the dropdown — via a JSON
  file (GRADIO_CATALOG_OVERLAY) or a per-node Additional Option. The curated
  public catalog stays clean; your org's private ZeroGPU Spaces stay yours. This is
  the upgrade that lets a team run production on hosted forks without maintaining a
  fork of the node.
• Custom Space — point at any Space by ID. The endpoint list and its parameter
  names are read live from the Space's own schema, so you pass arguments by name
  instead of hand-counting a positional array.

Built and maintained by Shadow Software — we run
n8n in production across a family of products and open-source the nodes we rely on.
See our other node, n8n-nodes-custom-exec,
for running shell tooling (ffmpeg, imagemagick, …) from a workflow.

Installation · Credentials · Usage · Catalog Overlay · Try it · Models · Quota · Compatibility

Installation

Follow the community nodes installation guide,
then search for n8n-nodes-huggingface-space.

Self-hosted, from the CLI:

npm install n8n-nodes-huggingface-space

Credentials

The node uses a Hugging Face Space API credential holding a single access token,
which you create at huggingface.co/settings/tokens.
A read token is enough.

The credential is optional — public Spaces accept anonymous calls. In practice you
want one anyway: an anonymous caller shares a very small ZeroGPU allowance with
everyone else on the same egress IP, so unauthenticated runs tend to fail with an
out-of-quota error as soon as they see real use. With a token, the call draws on your
own account's allowance.

Usage

Catalog mode

Pick a Category (Image, Text, Video, Music, Audio, Moderation, …) and a Model,
then write your Prompt. Everything else is optional.

Use Extra Parameters to pass anything the underlying Space accepts, by name —
width, height, num_inference_steps, seed, and so on. Names differ per Space;
anything the chosen Space doesn't declare is dropped and reported back in
droppedParams rather than failing the run.

Custom Space mode

Give a Space ID as it appears in the Space's URL (e.g. Tongyi-MAI/Z-Image-Turbo).
The API Endpoint dropdown then loads that Space's real endpoints, and you supply
arguments by their real names.

Catalog Overlay — curate your own model list

Host your own Gradio Spaces (private ZeroGPU forks of FLUX, Chatterbox, Qwen-Edit,
…), then tell the node to try those first while keeping the public catalog as
fallback. No fork of this package. No hard-coded org names in the curated list.

Fleet-wide (recommended for production)

Set an environment variable on the n8n process to a JSON file path (or inline JSON):

GRADIO_CATALOG_OVERLAY=/data/gradio-catalog-overlay.json

Example file:

{
  "version": 1,
  "prepend": {
    "image/flux2-dev": [
      { "space": "myorg/flux-2-dev", "api": "infer", "promptParam": "prompt" }
    ],
    "audio/chatterbox": [
      {
        "space": "myorg/chatterbox",
        "api": "generate_tts_audio",
        "promptParam": "text_input"
      }
    ]
  },
  "hideModels": ["image/sdxl"]
}

Restart n8n after editing the file (the env overlay is read when the node module
loads). Private Spaces still need a Hugging Face token on the credential that can
read them.

Per-workflow

Under Additional Options → Catalog Overlay, paste the same JSON. It merges on
top of the fleet env overlay (node prepends sit in front).

Keys are always category/modelId — the same ids as in the Models
tables below (image/flux2-dev, audio/chatterbox, …).

Output

{
  "gradio": {
    "space": "black-forest-labs/FLUX.2-dev",
    "apiName": "infer",
    "durationMs": 6647,
    "files": ["https://…hf.space/gradio_api/file=/tmp/gradio/…/image.webp"],
    "data":  [ /* the Space's raw return value */ ],
    "fallbacksTried": [],   // which Spaces failed first, and why
    "droppedParams": []     // extras the chosen Space does not declare
  }
}

files holds directly-fetchable https URLs. Enable Download Result Files to attach
the first one to the item as binary data instead.

Both fallbacksTried and droppedParams are surfaced deliberately: a silent fallback
means a different model answered than the one you asked for, and that should never be
invisible.

Try it — two one-click demo workflows

Every field below is set through the node's real UI — dropdowns and a text box, no
expressions, no JSON. Wire a Manual Trigger into the node, pick a category and model,
write a prompt, click Execute workflow.

Image — a "Shadowman" logo mark (watch it run)

▶ Full video (MP4) · same file under /assets/images

Open the node → pick Image + SDXL → write the prompt → execute:

SDXL's catalog entry includes a CPU-only fallback Space with zero GPU-quota cost, so
this image demo can run green without a Hugging Face PRO token.

Text (LLM) — a short blog post about AEO

Community text-generation Spaces are the most heavily used on Hugging Face and the
first to queue or error under load — this exact config returns a real blog post
once the underlying Space has room, with no changes needed.

Models

The catalog below is not a list of models that exist — it is a list of models that were
called successfully. Every entry was probed live: the Space was RUNNING, the endpoint
existed in its own schema, and it returned an artifact of the right kind.

That distinction matters more than it sounds. A keyword search for a model name will
happily return a Space that is running but publishes no callable endpoint, one that is
login-gated behind an OAuth wall, or one that returns a chart image where you expected a
label. Several very popular Spaces (thousands of likes) are exactly this. They are
excluded, and the ones that have no working Space at all stay listed in the dropdown but
are clearly marked unavailable, with the reason — a dead entry with an explanation
beats a dead entry that just fails at runtime.

Image

Text (LLM)

Video

Audio (TTS)

Voice Conversion

Lip Sync

Face Swap

Music

Moderation & Safety

Image Editing

Vision & OCR

Web

A note on GPU quota

Most of these Spaces run on Hugging Face ZeroGPU, which is metered per account, not
per Space. Two consequences are worth knowing before you build a workflow on this:

• A quota error is not a Space failure. When your allowance is spent, every ZeroGPU
  Space rejects you identically, so the node does not walk the fallback chain — that
  would just burn wall-clock collecting the same error N times. It fails fast and tells
  you when the quota resets.
• CPU-only Spaces are the exception. A handful of catalog entries (marked in their
  description) run on CPU and spend no GPU quota at all. They are slower, but they still
  work when everything else is locked out — so the node does fall through to them after
  a quota error. sdxl and the moderation models are the ones to reach for.

A Hugging Face PRO subscription raises the
allowance considerably, and is effectively required for video generation: a single video
call asks for more GPU-seconds than a free account may request at once.

Compatibility

• n8n 1.60.0 or later
• Node.js 20.15 or later

Tested against n8n 1.x.

Dependencies

The node has zero runtime dependencies — npm audit --omit=dev reports no
vulnerabilities, because nothing is shipped but the compiled node itself.

A plain npm audit does report advisories. Every one of them comes from
n8n-workflow, which is a peer dependency: n8n supplies it at runtime from its
own tree, so those advisories are resolved by upgrading n8n, not this package.
Pinning our own copy would only risk breaking compatibility with the host.

Links

• npm — n8n-nodes-huggingface-space
• Source — github.com/shadow-software/n8n-nodes-huggingface-space
• n8n community nodes — installation & docs
• Hugging Face Spaces — huggingface.co/spaces · Gradio API
• Also by us — n8n-nodes-custom-exec: run shell tooling (ffmpeg, imagemagick, pandoc, …) on a remote exec service from a workflow.

We also build and open-source a family of WordPress plugins and themes for
WooCommerce stores: Broadside
(theme) and Broadside Blocks,
Crypto for WooCommerce, and
AGT for WooCommerce.

About

Made by Shadow Software — we build and run
automation-heavy SaaS products and open-source the n8n nodes we depend on. If you
need custom n8n nodes, workflow automation, or a platform built around it, get in
touch at shadowsoftware.com.

License

MIT © Shadow Software