Hugging Face Inference Providers — free tier setup

What you get free

A permanent (but tiny) monthly credit allowance for HF's multi-provider router, which fronts Groq, Cerebras, Novita, Together, DeepInfra and more behind one OpenAI-compatible endpoint. Per the catalog: "Free Users: $0.10 monthly credits, 'subject to change'; PRO Users: $2.00; Team or Enterprise Organizations: $2.00 per seat. 'Every Hugging Face user receives monthly credits to experiment with Inference Providers.'" The gotcha: the quota is dollar-denominated, not request-denominated — $0.10/month evaporates after a handful of large-model calls, so this tier is for smoke-testing the router, not for real traffic.

Friction check


Credit card	no
Phone verification	no
Org/membership	none (any HF account)
Est. time to first key	~5m (3 steps)
Trains on your prompts	unknown — requests route to third-party providers; each upstream's data policy applies (not verified per provider)

Get a key

Sign up / log in at huggingface.co.
Go to hf.co/settings/tokens and create a new token. Official docs: generate a fine-grained token with "Make calls to Inference Providers" permissions (direct link: huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained).
Copy the token (hf_...). A plain read token also works for hf auth login per the docs, but the fine-grained inference permission is the documented path for API calls.

First request

Router base URL from the catalog, "drop-in replacement for the OpenAI chat completions API." Expected success shape: a JSON chat.completion object with choices[0].message.content.

export HF_TOKEN="YOUR_KEY"
curl https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 16
  }'

(Provider selection via model suffix: :fastest is the default policy, :cheapest picks lowest price per output token, :preferred follows your ordering at hf.co/settings/inference-providers, or pin an upstream with :<provider-name>, e.g. openai/gpt-oss-120b:groq. GET /v1/models lists models with per-provider pricing.)

Limits that will bite you

$0.10/month total, shared across all models and providers — credit-metered, no RPM/RPD/TPM numbers exist (catalog: shared_pool: true). On free credits, prefer :cheapest and small models.
Credits only apply to requests routed by Hugging Face — bring-your-own upstream keys bill upstream, not against credits.
Past free credits, usage is pay-as-you-go at provider rates (no HF markup) — it does not hard-stop for accounts with billing enabled; watch for surprise spend.
"Subject to change" is literal — the mnfst repo's "100K monthly credits" figure does not match the official pricing page; re-verify monthly.
OpenAI-compatible endpoint is chat completions only (openai_responses: false); other tasks need the HF InferenceClient. Automatic failover across upstreams with provider="auto".

Key rotation runbook

Second key: HF supports multiple tokens — create another fine-grained token at hf.co/settings/tokens with the same "Make calls to Inference Providers" permission. Note: credits are per account, so a second token does not add quota.
Revoke: delete or invalidate the token at hf.co/settings/tokens.
ModelHubby integration: export HF_TOKEN_2="..." — the key pool picks it up automatically; state machine cools down rate-limited keys per-key.

ModelHubby usage

pnpm mh show huggingface
pnpm mh probe --live --provider huggingface --apply