Jul 16, 2025 · Jun 4, 2025 · Jun 4, 2025 · Jun 4, 2025 · Jun 4, 2025 · Jun 9, 2025
diff --git a/docs/api/models/huggingface.md b/docs/api/models/huggingface.md
 # `pydantic_ai.models.huggingface`

 ## Setup

 For details on how to set up authentication with this model, see [model configuration for Hugging Face](../../models/huggingface.md).

 ::: pydantic_ai.models.huggingface
diff --git a/docs/api/providers.md b/docs/api/providers.md
 ::: pydantic_ai.providers.heroku.HerokuProvider

 ::: pydantic_ai.providers.openrouter.OpenRouterProvider

 ::: pydantic_ai.providers.huggingface.HuggingFaceProvider
diff --git a/docs/models/huggingface.md b/docs/models/huggingface.md
 # Hugging Face


 ## Install

 To use `HuggingFace`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `huggingface` optional group:
 To use `HuggingFaceModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `huggingface` optional group:

 ```bash
 pip/uv-add "pydantic-ai-slim[huggingface]"
 ```

 ## Configuration

 To use `HuggingFaceModel` through their main API, go to [Inference Providers documentation](https://huggingface.co/docs/inference-providers/pricing) for all the details, and you can generate a Hugging Face Token here: https://huggingface.co/settings/tokens.
 To use [HuggingFace](https://huggingface.co/) through their main API, go to
 [Inference Providers documentation](https://huggingface.co/docs/inference-providers/pricing) for all the details,
 and you can generate a Hugging Face access token here: https://huggingface.co/settings/tokens.

 ##Environment variable
 ##Hugging Face access token

 Once you have aHuggingFace Token, you can set it as an environment variable:
 Once you have aHugging Face access token, you can set it as an environment variable:

 ```bash
 export HF_TOKEN='hf_token'
 ```

 You can then use `HuggingFaceModel` by name:
 You can then use[`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] by name:

 ```python
 from pydantic_ai import Agent
 ...
 ```

 By default, the `HuggingFaceModel` uses the `HuggingFaceProvider` that will select automatically the first of the inference providers (Cerebras, Together AI, Cohere..etc) available for the model, sorted by your preferred order in https://hf.co/settings/inference-providers.
 By default, the [`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] uses the
 [`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] that will select automatically
 the first of the inference providers (Cerebras, Together AI, Cohere..etc) available for the model, sorted by your
 preferred order in https://hf.co/settings/inference-providers.

 ## Configure the provider

 If you want to pass parameters in code to the provider, you can programmatically instantiate the
 [HuggingFaceProvider][pydantic_ai.providers.huggingface.HuggingFaceProvider] and pass it to the model:
 [`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] and pass it to the model:

 ```python
 from pydantic_ai import Agent
 ...
 ```

 ## Custom Hugging FaceClient
 ## Custom Hugging Faceclient

 `HuggingFaceProvider` also accepts a custom `AsyncInferenceClient` client via the `hf_client` parameter, so you can customise the `headers`, `bill_to` (billing to an HF organization you're a member of), `base_url` etc. as defined in the [Hugging Face Hub python library docs](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client).
 [`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] also accepts a custom
 [`AsyncInferenceClient`][huggingface_hub.AsyncInferenceClient] client via the `hf_client` parameter, so you can customise
 the `headers`, `bill_to` (billing to an HF organization you're a member of), `base_url` etc. as defined in the
 [Hugging Face Hub python library docs](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client).

 ```python
 from huggingface_hub import AsyncInferenceClient
diff --git a/mkdocs.yml b/mkdocs.yml
      - api/models/gemini.md
      - api/models/google.md
      - api/models/groq.md
      - api/models/huggingface.md
      - api/models/instrumented.md
      - api/models/mistral.md
      - api/models/test.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,7 @@
		# `pydantic_ai.models.huggingface`

		## Setup

		For details on how to set up authentication with this model, see [model configuration for Hugging Face](../../models/huggingface.md).

		::: pydantic_ai.models.huggingface
Original file line number	Diff line number	Diff line change
Expand Up		@@ -29,3 +29,5 @@
		::: pydantic_ai.providers.heroku.HerokuProvider

		::: pydantic_ai.providers.openrouter.OpenRouterProvider

		::: pydantic_ai.providers.huggingface.HuggingFaceProvider
Original file line number	Diff line number	Diff line change
		@@ -1,27 +1,28 @@
		# Hugging Face


		## Install

		To use `HuggingFace`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `huggingface` optional group:
		To use `HuggingFaceModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `huggingface` optional group:

		```bash
		pip/uv-add "pydantic-ai-slim[huggingface]"
		```

		## Configuration

		To use `HuggingFaceModel` through their main API, go to [Inference Providers documentation](https://huggingface.co/docs/inference-providers/pricing) for all the details, and you can generate a Hugging Face Token here: https://huggingface.co/settings/tokens.
		To use [HuggingFace](https://huggingface.co/) through their main API, go to
		[Inference Providers documentation](https://huggingface.co/docs/inference-providers/pricing) for all the details,
		and you can generate a Hugging Face access token here: https://huggingface.co/settings/tokens.

		##Environment variable
		##Hugging Face access token

		Once you have aHuggingFace Token, you can set it as an environment variable:
		Once you have aHugging Face access token, you can set it as an environment variable:

		```bash
		export HF_TOKEN='hf_token'
		```

		You can then use `HuggingFaceModel` by name:
		You can then use[`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] by name:

		```python
		from pydantic_ai import Agent
Expand All		@@ -41,12 +42,15 @@ agent = Agent(model)
		...
		```

		By default, the `HuggingFaceModel` uses the `HuggingFaceProvider` that will select automatically the first of the inference providers (Cerebras, Together AI, Cohere..etc) available for the model, sorted by your preferred order in https://hf.co/settings/inference-providers.
		By default, the [`HuggingFaceModel`][pydantic_ai.models.huggingface.HuggingFaceModel] uses the
		[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] that will select automatically
		the first of the inference providers (Cerebras, Together AI, Cohere..etc) available for the model, sorted by your
		preferred order in https://hf.co/settings/inference-providers.

		## Configure the provider

		If you want to pass parameters in code to the provider, you can programmatically instantiate the
		[HuggingFaceProvider][pydantic_ai.providers.huggingface.HuggingFaceProvider] and pass it to the model:
		[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] and pass it to the model:

		```python
		from pydantic_ai import Agent
Expand All		@@ -58,9 +62,12 @@ agent = Agent(model)
		...
		```

		## Custom Hugging FaceClient
		## Custom Hugging Faceclient

		`HuggingFaceProvider` also accepts a custom `AsyncInferenceClient` client via the `hf_client` parameter, so you can customise the `headers`, `bill_to` (billing to an HF organization you're a member of), `base_url` etc. as defined in the [Hugging Face Hub python library docs](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client).
		[`HuggingFaceProvider`][pydantic_ai.providers.huggingface.HuggingFaceProvider] also accepts a custom
		[`AsyncInferenceClient`][huggingface_hub.AsyncInferenceClient] client via the `hf_client` parameter, so you can customise
		the `headers`, `bill_to` (billing to an HF organization you're a member of), `base_url` etc. as defined in the
		[Hugging Face Hub python library docs](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client).

		```python
		from huggingface_hub import AsyncInferenceClient
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -81,6 +81,7 @@ nav:
		- api/models/gemini.md
		- api/models/google.md
		- api/models/groq.md
		- api/models/huggingface.md
		- api/models/instrumented.md
		- api/models/mistral.md
		- api/models/test.md
Expand Down