Hugging Face (inference)

Hugging Face Inference Providers offer OpenAI-compatible chat completions through a single router API. You get access to many models (DeepSeek, Llama, and more) with one token. FluffBuzz uses the OpenAI-compatible endpoint (chat completions only); for text-to-image, embeddings, or speech use the HF inference clients directly.

Provider: huggingface
Auth: HUGGINGFACE_HUB_TOKEN or HF_TOKEN (fine-grained token with Make calls to Inference Providers)
API: OpenAI-compatible (https://router.huggingface.co/v1)
Billing: Single HF token; pricing follows provider rates with a free tier.

Getting started

Create a fine-grained token

Go to Hugging Face Settings Tokens and create a new fine-grained token.

The token must have the Make calls to Inference Providers permission enabled or API requests will be rejected.

Run onboarding

Choose Hugging Face in the provider dropdown, then enter your API key when prompted:

fluffbuzz onboard --auth-choice huggingface-api-key

Select a default model

In the Default Hugging Face model dropdown, pick the model you want. The list is loaded from the Inference API when you have a valid token; otherwise a built-in list is shown. Your choice is saved as the default model.You can also set or change the default model later in config:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

Verify the model is available

fluffbuzz models list --provider huggingface

Non-interactive setup

fluffbuzz onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

This will set huggingface/deepseek-ai/DeepSeek-R1 as the default model.

Model IDs

Model refs use the form huggingface/<org>/<model> (Hub-style IDs). The list below is from GET https://router.huggingface.co/v1/models; your catalog may include more.

Model	Ref (prefix with `huggingface/`)
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.2	`deepseek-ai/DeepSeek-V3.2`
Qwen3 8B	`Qwen/Qwen3-8B`
Qwen2.5 7B Instruct	`Qwen/Qwen2.5-7B-Instruct`
Qwen3 32B	`Qwen/Qwen3-32B`
Llama 3.3 70B Instruct	`meta-llama/Llama-3.3-70B-Instruct`
Llama 3.1 8B Instruct	`meta-llama/Llama-3.1-8B-Instruct`
GPT-OSS 120B	`openai/gpt-oss-120b`
GLM 4.7	`zai-org/GLM-4.7`
Kimi K2.5	`moonshotai/Kimi-K2.5`

You can append :fastest or :cheapest to any model id. Set your default order in Inference Provider settings; see Inference Providers and GET https://router.huggingface.co/v1/models for the full list.

Advanced configuration

FluffBuzz discovers models by calling the Inference endpoint directly:

GET https://router.huggingface.co/v1/models

(Optional: send Authorization: Bearer $HUGGINGFACE_HUB_TOKEN or $HF_TOKEN for the full list; some endpoints return a subset without auth.) The response is OpenAI-style { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.When you configure a Hugging Face API key (via onboarding, HUGGINGFACE_HUB_TOKEN, or HF_TOKEN), FluffBuzz uses this GET to discover available chat-completion models. During interactive setup, after you enter your token you see a Default Hugging Face model dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, FluffBuzz again calls GET https://router.huggingface.co/v1/models to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.

Model names, aliases, and policy suffixes

Name from API: The model display name is hydrated from GET /v1/models when the API returns name, title, or display_name; otherwise it is derived from the model id (e.g. deepseek-ai/DeepSeek-R1 becomes “DeepSeek R1”).
Override display name: You can set a custom label per model in config so it appears the way you want in the CLI and UI:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

Policy suffixes: FluffBuzz’s bundled Hugging Face docs and helpers currently treat these two suffixes as the built-in policy variants:
- :fastest — highest throughput.
- :cheapest — lowest cost per output token.
You can add these as separate entries in models.providers.huggingface.models or set model.primary with the suffix. You can also set your default provider order in Inference Provider settings (no suffix = use that order).
Config merge: Existing entries in models.providers.huggingface.models (e.g. in models.json) are kept when config is merged. So any custom name, alias, or model options you set there are preserved.

Environment and daemon setup

If the Gateway runs as a daemon (launchd/systemd), make sure HUGGINGFACE_HUB_TOKEN or HF_TOKEN is available to that process (for example, in ~/.fluffbuzz/.env or via env.shellEnv).

FluffBuzz accepts both HUGGINGFACE_HUB_TOKEN and HF_TOKEN as env var aliases. Either one works; if both are set, HUGGINGFACE_HUB_TOKEN takes precedence.

Config: DeepSeek R1 with Qwen fallback

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/Qwen/Qwen3-8B"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
      },
    },
  },
}

Config: Qwen with cheapest and fastest variants

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen3-8B" },
      models: {
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
      },
    },
  },
}

Config: DeepSeek + Llama + GPT-OSS with aliases

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
        fallbacks: [
          "huggingface/meta-llama/Llama-3.3-70B-Instruct",
          "huggingface/openai/gpt-oss-120b",
        ],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
        "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

Config: Multiple Qwen and DeepSeek with policy suffixes

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
      models: {
        "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
      },
    },
  },
}

Model selection

Overview of all providers, model refs, and failover behavior.

Model selection

How to choose and configure models.

Inference Providers docs

Official Hugging Face Inference Providers documentation.

Configuration

Full config reference.

​Getting started

​Non-interactive setup

​Model IDs

​Advanced configuration

​Related

Model selection

Model selection

Inference Providers docs

Configuration

Getting started

Non-interactive setup

Model IDs

Advanced configuration

Related