# Hugging Face Inference Providers: First API Request

> One HF token, one endpoint: call an open model with InferenceClient, the OpenAI SDK or curl, pick a provider, and see how billing works.

- Canonical: https://guides-ai.com/guides/hugging-face-inference-providers-first-request/
- Plate 16.07 · Topic: Hugging Face (https://guides-ai.com/topics/huggingface/)
- Published: 12 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

[Inference Providers](https://huggingface.co/docs/inference-providers/index) is Hugging Face's serverless API: one HF token, one endpoint, and each request is routed to a partner (Groq, Together, Cerebras, Fireworks and others) that runs the open model you named. No GPU, no download.

## 1. Token

Create a fine-grained token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) with the **Make calls to Inference Providers** permission, then export it:

```bash
export HF_TOKEN="hf_your_token_here"
```

```powershell
$env:HF_TOKEN = "hf_your_token_here"
```

Both SDKs below read it from the environment. `hf auth login` stores a token on disk instead; `HF_TOKEN` wins when both exist.

## 2. InferenceClient (Python)

```bash
pip install -U huggingface_hub
```

```python
from huggingface_hub import InferenceClient

client = InferenceClient()  # reads HF_TOKEN or the token saved by `hf auth login`

completion = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[{"role": "user", "content": "Explain HTTP 402 in one sentence."}],
)

print(completion.choices[0].message.content)
```

Sends one chat turn and prints the reply. `chat.completions.create` is an alias of `chat_completion`; both return the OpenAI response shape.

## 3. OpenAI SDK

```bash
pip install -U openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model="openai/gpt-oss-120b:fastest",
    messages=[{"role": "user", "content": "Explain HTTP 402 in one sentence."}],
)

print(completion.choices[0].message.content)
```

The same call through the OpenAI-compatible router: existing [OpenAI code](/guides/openai-api-first-request/) only needs a new base URL, your HF token and a Hub model id. This endpoint is chat-only; images, embeddings and speech go through `InferenceClient`.

## 4. curl

```bash
curl https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b:fastest",
    "messages": [{"role": "user", "content": "Explain HTTP 402 in one sentence."}],
    "stream": false
  }'
```

Returns one JSON chat completion. For token-by-token output see [streaming responses](/guides/stream-llm-responses/). `GET https://router.huggingface.co/v1/models` lists every routed model with per-provider price, context length and throughput.

## 5. Provider and billing

By default the router picks the fastest live provider (highest tokens per second). A suffix on the model id changes that:

```text
openai/gpt-oss-120b:fastest     # default policy
openai/gpt-oss-120b:cheapest    # lowest price per output token
openai/gpt-oss-120b:preferred   # your order in Inference Provider settings
openai/gpt-oss-120b:groq        # always this provider
```

With `InferenceClient` you can pass `provider="groq"` instead; the default is `"auto"`, which also fails over when a provider is flagged unavailable.

Billing per the [pricing page](https://huggingface.co/docs/inference-providers/pricing): pay-as-you-go at the provider's own rate, no Hugging Face markup. PRO users and Team/Enterprise seats get monthly included credits; free accounts get none and must buy credits first. Amounts change, so read the page, not a blog post. Per-model and per-provider usage is on [your Inference Providers settings](https://huggingface.co/settings/inference-providers/overview).

## If it fails

- **`401` `{"error":"Invalid username or password."}`** (`AuthenticationError` in the OpenAI SDK, `HfHubHTTPError` in `huggingface_hub`): the token is missing or invalid. Create a new fine-grained token with the Inference Providers permission and re-export it.
- **`402 Payment Required`**: no credits left, or a free account with none bought. Add credits on the [billing page](https://huggingface.co/settings/billing).
- **`503 Service Unavailable` with a pinned provider**: that provider is down. Drop the `:provider` suffix so the router can fail over, or pin another one listed on the model page.

---

Next: [run a small model locally instead](/guides/transformers-pipeline-quickstart/) · [pick an AI model](/guides/pick-an-ai-model/) · [serve your own OpenAI-compatible endpoint with vLLM](/guides/vllm-serve-openai-compatible/).