---
name: hugging-face
description: Download open models and datasets from Hugging Face and run open image, speech and chat models through its Inference Providers. Use when the user wants an open-weights model, a model to run locally, or a model that's only on Hugging Face. Needs HF_TOKEN.
---

# Hugging Face

Key: `HF_TOKEN` (the name Hugging Face's own tools read). Get one at https://huggingface.co/settings/tokens

## Download a model

```bash
pip install -U huggingface_hub
hf download black-forest-labs/FLUX.1-schnell --local-dir ./flux-schnell
```

`hf` reads `HF_TOKEN` by itself. Gated models (some Flux and Llama ones) need you to accept their terms on the model page first.

## Run an open model in the cloud

The router speaks OpenAI's format for chat:

```bash
curl -s https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"moonshotai/Kimi-K3","messages":[{"role":"user","content":"Three taglines for a bike shop."}]}'
```

And an image, through a provider that serves the model:

```bash
curl -s https://router.huggingface.co/nscale/v1/images/generations \
  -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"black-forest-labs/FLUX.1-schnell","prompt":"A lighthouse in a storm, oil painting","response_format":"b64_json"}'
```

The picture is base64 in `data[0].b64_json`.

## Notes

- Inference needs credits on the account (PRO includes $2 a month). A 402 means there are none.
- The token needs "Make calls to Inference Providers" for cloud runs. A read token is enough for downloads.
- Chat models the router serves right now: `curl -s https://router.huggingface.co/v1/models`.
- Which provider serves an image model: open the model page and look under "Inference Providers".