Menu

Mattering Automations Hugging Face integration

Connect Hugging Face to Mattering Automations: chat completions routed across Inference Providers, embeddings, summarization, translation, classification, image generation, and transcription, plus search, metadata, and repo management for the Hub catalog, authenticated with one User Access Token.

The Mattering Automations Hugging Face integration puts both halves of Hugging Face on your automation canvas. The inference half rides Inference Providers, Hugging Face's serverless router: run an OpenAI-compatible chat completion with server-side provider routing, or use the task pipelines on Hugging Face's own hf-inference compute for embeddings, summarization, translation, zero-shot and standard text classification, image generation, speech transcription, and image classification. The Hub half is the catalog itself: search models, datasets, Spaces, papers, and collections, inspect metadata, file trees, and refs, watch trending repos and Space runtimes, and create, delete, like, or unlike repos.

Setup is one User Access Token from your Hugging Face account. This guide covers creating the token with the right permissions, connecting it, a verify path that costs nothing, the full 36 node reference, and the failure modes worth recognizing on sight.

Before you start

  • A Hugging Face account at huggingface.co. A free account works: Hub reads are free within rate limits, and Hugging Face's pricing docs currently list $0.10 of included monthly Inference Providers credits on free accounts, an amount they mark as subject to change, so light inference testing works before any payment is set up.
  • A Mattering workspace with access to the Automations app.
  • For the inference nodes beyond the included credits, a Hugging Face payment method or PRO subscription, since usage past the credits is pay-as-you-go on your Hugging Face account.
  • For the transcription and image classification nodes, the audio or image as a base64 string from an upstream node. These pipelines take base64 input, not URLs.
  • For the repo write nodes (create, delete, like, unlike), a token with write access. Read-only tokens cover every query node.

Create a Hugging Face User Access Token

Mattering authenticates to Hugging Face with a User Access Token sent as an Authorization bearer header on both Hugging Face hosts. It is a single field: no organization id, no second secret, no OAuth flow to complete.

Sign in at huggingface.co and open Settings, then Access Tokens.
Click Create new token and choose the fine-grained type.
Under permissions, enable Make calls to Inference Providers and read access to repos. Add repo write only if the workflow will create, delete, like, or unlike repos.
The token starts with hf_ and is shown once at creation. Copy it before closing the dialog; afterwards it can only be invalidated and recreated.
Copy the token and keep it somewhere safe until you have pasted it into Mattering.

Connect Hugging Face to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Hugging Face from the list.
Click Create new credential, paste the token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. It calls Hugging Face's free whoami endpoint, so a valid token passes without spending anything and a bad one fails with a 401 on the spot.
Click Connect. All 36 Hugging Face nodes appear in your canvas palette.

Verify it works

Open any automation canvas and check the palette: a Hugging Face section should list 22 query nodes and 14 action nodes. Drop Hugging Face: Who Am I onto the canvas and run a test step. It is free and side-effect free, and a successful response returns the account behind the token plus the token's own role and scopes, which confirms in one call that the credential is valid and shows exactly what it is allowed to do. Do not wire it into a polling loop: it counts against the Hub API rate limit like any other call.

To confirm inference itself works, add Hugging Face: Create Embeddings with the default sentence-transformers model and one short input string. It runs on CPU for fractions of a cent in credits and returns one float vector per input. For chat, run Hugging Face: Chat Completion with a small max_tokens value; the reply lands at data.choices[0].message.content.

Node reference

36 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 22

Hugging Face: Get Collection

hf_get_collection

Get one collection with its ordered items (models, datasets, Spaces, and papers) and per-item notes. Free read.

Hugging Face: Get Dataset

hf_get_dataset

Get full metadata for one dataset: downloads, likes, tags, card data, and sibling files. Free read.

Hugging Face: Get Model

hf_get_model

Get full metadata for one model: downloads, likes, pipeline tag, tags, license card data, sibling file list, and gating status. Ask for extra computed properties (downloadsAllTime, inference, inferenceProviderMapping) via expand[]. Free read.

Hugging Face: Get Paper

hf_get_paper

Get one indexed paper by its arXiv id: title, abstract, authors, and community upvotes. Free read.

Hugging Face: Get Router Model

hf_get_router_model

Get the provider line-up for one served chat model: which providers are live, their pricing, context windows, and capability flags. Free read.

Hugging Face: Get Space

hf_get_space

Get full metadata for one Space: SDK, likes, tags, sibling files, and its current runtime block (stage and hardware). Free read.

Hugging Face: Get Space Runtime

hf_get_space_runtime

Get the live runtime state of a Space: stage (RUNNING, SLEEPING, BUILDING, RUNTIME_ERROR, ...), current and requested hardware, and sleep timeout. Handy for monitoring a deployed demo from an automation. Free read.

Hugging Face: Get User Overview

hf_get_user_overview

Get a user's public profile overview: full name, plan, and counts of models, datasets, Spaces, followers, and likes. Free read.

Hugging Face: List Collections

hf_list_collections

List curated Hub collections, optionally filtered to one owner or to collections containing a specific item. Free read.

Hugging Face: List Daily Papers

hf_list_daily_papers

List the community-curated Daily Papers feed - trending ML research with upvotes and summaries. Great source material for a research digest automation. Free read.

Hugging Face: List Dataset Files

hf_list_dataset_files

List the files in a dataset repo at a given revision, with size and LFS info per entry. Paginated via cursor. Free read.

Hugging Face: List Model Files

hf_list_model_files

List the files in a model repo at a given revision: path, size, and LFS pointer info per entry. Paginated via cursor. Free read.

Hugging Face: List Model Refs

hf_list_model_refs

List the branches and tags of a model repo with the commit each one points at. Free read.

Hugging Face: List Repo Likers

hf_list_repo_likers

List the users who liked a repo (model, dataset, or Space). Paginated. Free read.

Hugging Face: List Router Models

hf_list_router_models

List every chat-completion model currently served by Inference Providers, with per-provider status, context length, pricing per million tokens, tool support, latency, and throughput. Use it to pick a model before a Chat Completion node. Free read.

Hugging Face: List Trending Repos

hf_list_trending

List what is trending on the Hub right now across models, datasets, and Spaces. A ready-made source for a weekly AI-news digest automation. Free read.

Hugging Face: List User Likes

hf_list_user_likes

List the public repos (models, datasets, Spaces) a user has liked, newest first. Free read.

Hugging Face: Search Datasets

hf_search_datasets

Search and filter the Hub's dataset catalog by keyword, author, or tag. Returns id, downloads, likes, and tags per dataset. Free read.

Hugging Face: Search Models

hf_search_models

Search and filter the Hub's model catalog: by keyword, author, task (pipeline_tag), library, or which inference provider currently serves the model. Returns id, downloads, likes, and tags per model. Free read.

Hugging Face: Search Papers

hf_search_papers

Full-text search over papers indexed on the Hub. Returns matching papers with ids and summaries; feed an id into the Get Paper node for detail. Free read.

Hugging Face: Search Spaces

hf_search_spaces

Search and filter Hugging Face Spaces (hosted ML demo apps) by keyword, author, or tag. Returns id, likes, and SDK per Space. Free read.

Hugging Face: Who Am I

hf_whoami

Validate the connected Hugging Face token and return the account behind it: username, orgs, plan, and the token's own role and scopes. Free and side-effect free, so it doubles as the credential health check.

Action nodes 14

Hugging Face: Chat Completion

hf_chat_completion

Run an OpenAI-compatible chat completion against any conversational model served by Hugging Face Inference Providers. The router picks the fastest live provider by default; steer it by appending :cheapest or a provider name like :groq to the model id. The reply text lands at data.choices[0].message.content. Consumes Inference Providers credits.

Hugging Face: Classify Image

hf_classify_image

Classify an image with a vision model: send the image as a base64-encoded string and get label/score pairs back. Useful for content screening or routing uploads in an automation.

Hugging Face: Classify Text

hf_classify_text

Classify text with a model trained for a fixed label set - sentiment, toxicity, language detection, and similar. Returns label/score pairs. For labels the model was not trained on, use the Zero-Shot node instead.

Hugging Face: Create Embeddings

hf_generate_embeddings

Turn text into embedding vectors (feature extraction) with a sentence-transformers style model. Send one string or a JSON array of strings and get one float vector per input as an array of arrays. Keep batches modest: every vector is a large float array in the execution record.

Hugging Face: Create Repo

hf_create_repo

Create a new empty repo on the Hub: a model, dataset, or Space (Spaces also need an sdk). The token must have write access. Reversible with the Delete Repo node.

Hugging Face: Delete Repo

hf_delete_repo

Permanently delete a repo (model, dataset, or Space) the token can administer. This cannot be undone and removes all files and history - point it only at repos this automation created.

Hugging Face: Generate Image

hf_generate_image

Generate an image from a text prompt with a diffusion model. The API returns raw image bytes; this node base64-encodes them at data.image_base64 with data.content_type, ready to pipe into an upload or email node. Image generation runs on GPU and bills by compute time; expect several seconds per image and a large execution record.

Hugging Face: Generate Text

hf_generate_text

Raw text-generation (completion-style) inference on an hf-inference hosted model: send a prompt, get its continuation at data[0].generated_text. For instruction following prefer the Chat Completion node; this pipeline suits base models like GPT-2. Cold models return 503 with an estimated_time to retry after.

Hugging Face: Like a Repo

hf_like_repo

Like a model, dataset, or Space as the connected account. Reversible with the Unlike node.

Hugging Face: Summarize Text

hf_summarize_text

Produce a shorter version of a document with a dedicated summarization model. The summary lands at data[0].summary_text. Cold models return 503 with an estimated_time to retry after.

Hugging Face: Transcribe Audio

hf_transcribe_audio

Transcribe speech to text with a Whisper-family model. Send the audio as a base64-encoded string (pipe it from an upstream file or HTTP node); the transcript lands at data.text. Long recordings take a while - the node allows up to 120 seconds.

Hugging Face: Translate Text

hf_translate_text

Translate text with a translation model. The result lands at data[0].translation_text. Language pairs are model-dependent: single-pair models (e.g. Helsinki-NLP/opus-mt-en-fr) need no parameters; multilingual models take src_lang and tgt_lang.

Hugging Face: Unlike a Repo

hf_unlike_repo

Remove the connected account's like from a model, dataset, or Space. The mirror of the Like node.

Hugging Face: Zero-Shot Classify Text

hf_zero_shot_classify_text

Classify text against labels you invent on the fly - no training needed. Supply candidate labels like refund or complaint and get a score per label, ideal for routing tickets, tagging form submissions, or triaging content in an automation.

Using the integration

On the automation canvas

Hugging Face nodes chain with everything else: pull a record, classify or generate with a Hugging Face step, then write the result into a task, a message, or a database row. Template references resolve inside nested JSON, so an upstream node's output drops straight into one entry of the messages array on chat or the inputs field on a pipeline node, rather than templating the whole payload as a single blob.

Chat with server-side provider routing

Hugging Face: Chat Completion speaks the OpenAI-compatible shape against the Inference Providers router, which picks the fastest live provider for the model by default. Steer it by appending :cheapest, :preferred, or a provider name like :groq to the model id. Pick models with Hugging Face: List Router Models, which lists every served chat model with per-provider pricing per million tokens, context length, tool support, latency, and throughput, and Hugging Face: Get Router Model shows one model's full provider line-up. Hugging Face documents this endpoint for chat completion tasks only, which is why the non-chat work ships as dedicated pipeline nodes.

Task pipelines on hf-inference

The pipeline nodes run on hf-inference, Hugging Face's own compute and the one provider that serves the classic task pipelines without a third-party account. Hugging Face: Create Embeddings handles feature extraction for search and RAG, Hugging Face: Summarize Text and Hugging Face: Translate Text cover documents, Hugging Face: Zero-Shot Classify Text scores text against labels you invent on the fly while Hugging Face: Classify Text covers models trained on a fixed label set, and Hugging Face: Generate Text runs completion-style generation on base models. Model fields are free text with documented defaults; find pipeline models that hf-inference actually serves with Hugging Face: Search Models using its provider and task filters.

Images and audio

Hugging Face: Generate Image turns a prompt into an image with a diffusion model and returns it as base64 with a content type, ready to pipe into an upload or email step; it runs on GPU, bills by compute time, and produces a large execution record, so use it deliberately. Hugging Face: Transcribe Audio and Hugging Face: Classify Image go the other direction: they take the audio or image as a base64 string templated from an upstream node, not a URL, and transcription allows up to 120 seconds for long recordings.

The Hub as a research surface

Hugging Face: Search Models, Hugging Face: Search Datasets, and Hugging Face: Search Spaces filter the catalog by keyword, author, task, or tag, and Hugging Face: Get Model, Hugging Face: Get Dataset, and Hugging Face: Get Space return full metadata including downloads, likes, license, and gating. Hugging Face: List Daily Papers reads the community-curated research feed, Hugging Face: Search Papers and Hugging Face: Get Paper cover the paper index, Hugging Face: List Trending Repos reads what is rising right now, and Hugging Face: List Collections and Hugging Face: Get Collection follow curated collections. Chained into a summarization or chat step on a schedule, these make a self-writing research digest.

Watching repos and Spaces

Hugging Face: List Model Files and Hugging Face: List Dataset Files walk a repo's file tree with sizes, Hugging Face: List Model Refs lists branches and tags with the commit each points at, which makes new-revision detection a one-node check, and Hugging Face: Get Space Runtime reports a Space's live stage and hardware so a scheduled workflow can page you when a deployed demo stops RUNNING. Hugging Face: Get User Overview, Hugging Face: List User Likes, and Hugging Face: List Repo Likers cover the social layer.

Repo lifecycle actions

Hugging Face: Create Repo scaffolds an empty model, dataset, or Space repo and Hugging Face: Delete Repo permanently removes one the token can administer, so point deletion only at repos the automation created. Note both take the repo name without its namespace, with the organization as its own optional field. Hugging Face: Like a Repo and Hugging Face: Unlike a Repo are a clean reversible pair. Pushing files into a repo needs a commit protocol the canvas cannot produce, so content uploads stay in CI and SDKs.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter can drive them and build workflows around them. Hugging Face also runs its own official MCP server at hf.co/mcp for Hub search and Spaces inside a conversation; this integration is the complementary piece that puts Hugging Face into scheduled and triggered workflows that run with no assistant in the loop.

Troubleshooting

Test Connection or every node returns a 401
The token is wrong, revoked, or truncated on paste; Hugging Face answers with an invalid credentials error. Tokens are shown once at creation, so if it was not copied cleanly there is nothing to recover: create a fresh token at huggingface.co under Settings, then Access Tokens, update the credential on the connector, and click Test Connection again. The check is free.
Query nodes work but likes or repo creation return a 403
The token lacks write access. A classic read-only token or a fine-grained token without repo write covers every query node but is rejected on Hugging Face: Like a Repo, Hugging Face: Unlike a Repo, Hugging Face: Create Repo, and Hugging Face: Delete Repo. Similarly, a fine-grained token without the Make calls to Inference Providers permission fails on the inference nodes while Hub reads keep working. Run Hugging Face: Who Am I to see the token's actual role and scopes, then recreate the token with the missing permission.
A pipeline node returns a 503
The model is cold. hf-inference answers 503 with an estimated load time while it spins a model up, and the node surfaces that as a retry hint on the execution record so it does not read like an auth failure. Wait roughly the estimated time and run the step again. The documented default models are popular and usually warm; a long-tail model you picked yourself will cold start more often.
Hub nodes start returning 429
You have hit the Hub API rate limit, which Hugging Face's docs currently list as 1,000 requests per 5 minutes for an authenticated free account, with higher tiers above that. The 429 response carries standard RateLimit headers that say when the window resets. Space the workflow out or reduce per-run call volume, and never poll Hugging Face: Who Am I on a loop: it draws from the same rate limit as every other Hub call.
An inference node fails with a payment or credits error
The account has used its included Inference Providers credits. Hugging Face's pricing docs currently list $0.10 per month included on free accounts, marked subject to change, and $2.00 per month on PRO; past the credits, usage is pay-as-you-go at the provider's listed price, and free accounts need to purchase credits for that. Resolve it on the Hugging Face side by adding credits or upgrading, then rerun the step. Hub query nodes are unaffected: they stay free within rate limits.
Chat works but a pipeline node cannot find the model
The model is not served by hf-inference. The pipeline nodes are pinned to Hugging Face's own compute, which serves a subset of the catalog, so a model that works on Hugging Face: Chat Completion through another provider can still be unavailable as a pipeline. Run Hugging Face: Search Models with the provider filter set to hf-inference and the task you need, and use a model from that list, or keep the documented default.
Transcription or image classification rejects the input
These nodes take the media as a base64 string in the inputs field, templated from an upstream file or HTTP step; they do not fetch URLs, so pasting a link produces a model-side error rather than a transcript. Check the upstream node actually emits base64, and for audio keep recordings within what 120 seconds of processing can handle. If the base64 is valid and the model still refuses, test with the documented default model first to separate a model problem from an input problem.
There is no node for the endpoint you need
Some gaps are deliberate. Uploading files into repos requires a multi-part commit protocol the canvas cannot produce, so content pushes stay in CI and SDKs while Hugging Face: Create Repo and Hugging Face: Delete Repo cover the lifecycle around them. Text to speech and text to video are served only by third-party providers with provider-specific request shapes and are not shipped. Streaming is out of scope: every node returns one complete response, and stream flags are stripped from outbound bodies. Discussions and pull requests, webhook management, organization administration, the Jobs API, and dedicated Inference Endpoints sit outside this connector.

Hugging Face is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products