Set up Hugging Face

Set up Hugging Face

Uses Hugging Face Inference Providers to run a hosted chat-completion model with a Hugging Face access token.

Before you start

You need a Hugging Face account and an access token with permission to call Inference Providers. Create one under your Hugging Face account settings; a read token is normally sufficient.

You also need a model that is available through Inference Providers and supports chat completion. Not every model on the Hub is — plenty are download-only, and pointing the plugin at one of those produces an error that looks like a configuration problem but is not.

Configure the plugin

Settings › AI Fun Questions, choose the Hugging Face card:

Field	Default	Notes
Hugging Face Token	(empty)	Your access token, or define a constant — below
Hugging Face Model	google/gemma-2-2b-it	Must be a chat-completion model on Inference Providers

Save, then load a page with the shortcode. There is no test button.

Put the token in wp-config.php instead

define( 'AI_FQ_HF_TOKEN', 'hf_…' );

The constant wins over the saved value, and the settings screen will say so. See Keeping API Keys Out of the Database for why this is worth doing.

The endpoint is fixed

Unlike the OpenAI-compatible provider, there is no endpoint field. This provider always calls the Hugging Face router:

https://router.huggingface.co/v1/chat/completions

That is hard-coded. If you need to point at a different host — a dedicated Inference Endpoint, or a self-hosted deployment — use the OpenAI-compatible provider instead and set its endpoint to your URL. It speaks the same API shape.

Notes

• Requests time out after 30 seconds and follow at most 2 redirects.
• The reply is read from choices[0].message.content, the same shape as OpenAI.
• Small models sometimes fail to return valid JSON reliably. If you see frequent "invalid response" errors, that is usually the model rather than the plugin — try a larger instruct-tuned one.
• Free-tier Inference Providers usage is rate limited by Hugging Face. Their limit is separate from the plugin's own and will surface as "temporarily unavailable".

If it does not work

Symptom	Likely cause
"The Hugging Face configuration is invalid."	Token or model field is empty
"The AI service is temporarily unavailable."	Bad token, model not available on Inference Providers, upstream rate limit, or timeout
"The AI provider returned an invalid response."	The model did not return usable JSON — try a larger model
"The AI response did not meet the required content limits."	The reply was too long, or empty once sanitised

The most common cause of "temporarily unavailable" here is a model that exists on the Hub but is not served by Inference Providers. Check the model page for an inference widget before assuming your token is wrong.