From 1f46db27e910b51154b31e1a627ed2e94555c546 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Thu, 4 Jun 2026 17:14:57 +0200
Subject: [PATCH 1/2] chore: deprecate HF API components + update docs

---
 .../huggingfaceapidocumentembedder.mdx        | 65 +++++++++++++------
 .../embedders/huggingfaceapitextembedder.mdx  | 28 +++++---
 .../huggingfaceapichatgenerator.mdx           | 44 +++++++++----
 .../huggingfaceapidocumentembedder.mdx        | 65 +++++++++++++------
 .../embedders/huggingfaceapitextembedder.mdx  | 28 +++++---
 .../huggingfaceapichatgenerator.mdx           | 44 +++++++++----
 .../hugging_face_api_document_embedder.py     | 10 +++
 .../hugging_face_api_text_embedder.py         | 10 +++
 .../generators/chat/hugging_face_api.py       |  9 +++
 ...te-hf-api-components-d6935cc408fdcf1a.yaml | 13 ++++
 10 files changed, 240 insertions(+), 76 deletions(-)
 create mode 100644 releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml

diff --git a/docs-website/docs/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx b/docs-website/docs/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
index 29aae96538..d35f8ef3c3 100644
--- a/docs-website/docs/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
+++ b/docs-website/docs/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
@@ -17,9 +17,9 @@ Use this component to compute document embeddings using various Hugging Face API
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.  <br /> <br />`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `documents`: A list of documents to be embedded |
 | **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) |
-| **API reference** | [Embedders](/reference/embedders-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -43,8 +43,14 @@ The token is needed:
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPIDocumentEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 Similarly to other Document Embedders, this component allows adding prefixes (and postfixes) to include instruction and embedding metadata.
-For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapidocumentembedder).
+For more fine-grained details, refer to the component’s [API reference](/reference/integrations-huggingface-api#huggingfaceapidocumentembedder).
 
 ### On its own
 
@@ -56,7 +62,9 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Embedder expects the `model` in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.utils import Secret
 from haystack.dataclasses import Document
 
@@ -84,7 +92,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Embedder expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.utils import Secret
 from haystack.dataclasses import Document
 
@@ -123,7 +133,9 @@ For more information, refer to the [official TEI repository](https://github.com/
 The Embedder expects the `url` of your TEI instance in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.dataclasses import Document
 
 doc = Document(content="I love pizza!")
@@ -145,38 +157,53 @@ print(result["documents"][0].embedding)
 from haystack import Document
 from haystack import Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
-from haystack.components.embedders import HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.components.writers import DocumentWriter
 from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
 
 document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
 
-documents = [Document(content="My name is Wolfgang and I live in Berlin"),
-             Document(content="I saw a black horse running"),
-             Document(content="Germany has many big cities")]
+documents = [
+    Document(content="My name is Wolfgang and I live in Berlin"),
+    Document(content="I saw a black horse running"),
+    Document(content="Germany has many big cities"),
+]
 
-document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
-				                                           api_params={"model": "BAAI/bge-small-en-v1.5"})
+document_embedder = HuggingFaceAPIDocumentEmbedder(
+    api_type="serverless_inference_api",
+    api_params={"model": "BAAI/bge-small-en-v1.5"},
+)
 
 indexing_pipeline = Pipeline()
 indexing_pipeline.add_component("document_embedder", document_embedder)
-indexing_pipeline.add_component("doc_writer", DocumentWriter(document_store=document_store)
+indexing_pipeline.add_component(
+    "doc_writer",
+    DocumentWriter(document_store=document_store),
+)
 indexing_pipeline.connect("document_embedder", "doc_writer")
 indexing_pipeline.run({"document_embedder": {"documents": documents}})
 
-text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
-                                           api_params={"model": "BAAI/bge-small-en-v1.5"})
+text_embedder = HuggingFaceAPITextEmbedder(
+    api_type="serverless_inference_api",
+    api_params={"model": "BAAI/bge-small-en-v1.5"},
+)
 
 query_pipeline = Pipeline()
 query_pipeline.add_component("text_embedder", text_embedder)
-query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.add_component(
+    "retriever",
+    InMemoryEmbeddingRetriever(document_store=document_store),
+)
 query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
 
 query = "Who lives in Berlin?"
 
-result = query_pipeline.run({"text_embedder":{"text": query}})
+result = query_pipeline.run({"text_embedder": {"text": query}})
 
-print(result['retriever']['documents'][0])
+print(result["retriever"]["documents"][0])
 
 # Document(id=..., content: 'My name is Wolfgang and I live in Berlin', ...)
 ```
diff --git a/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx b/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx
index 0e7f68ff29..436c92512b 100644
--- a/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx
+++ b/docs-website/docs/pipeline-components/embedders/huggingfaceapitextembedder.mdx
@@ -17,9 +17,9 @@ Use this component to embed strings using various Hugging Face APIs.
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.  <br /> <br />`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `text`: A string |
 | **Output variables** | `embedding`: A list of float numbers |
-| **API reference** | [Embedders](/reference/embedders-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -43,8 +43,14 @@ The token is needed:
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPITextEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 Similarly to other text Embedders, this component allows adding prefixes (and postfixes) to include instructions.
-For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapitextembedder).
+For more fine-grained details, refer to the component’s [API reference](/reference/integrations-huggingface-api#huggingfaceapitextembedder).
 
 ### On its own
 
@@ -56,7 +62,9 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Embedder expects the `model` in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -80,7 +88,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Embedder expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -115,7 +125,9 @@ For more information, refer to the [official TEI repository](https://github.com/
 The Embedder expects the `url` of your TEI instance in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -134,7 +146,7 @@ print(text_embedder.run("I love pizza!"))
 from haystack import Document
 from haystack import Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
-from haystack.components.embedders import (
+from haystack_integrations.components.embedders.huggingface_api import (
     HuggingFaceAPITextEmbedder,
     HuggingFaceAPIDocumentEmbedder,
 )
diff --git a/docs-website/docs/pipeline-components/generators/huggingfaceapichatgenerator.mdx b/docs-website/docs/pipeline-components/generators/huggingfaceapichatgenerator.mdx
index debaa6376f..343a7f7bf3 100644
--- a/docs-website/docs/pipeline-components/generators/huggingfaceapichatgenerator.mdx
+++ b/docs-website/docs/pipeline-components/generators/huggingfaceapichatgenerator.mdx
@@ -17,9 +17,9 @@ This generator enables chat completion using various Hugging Face APIs.
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat or a plain string |
 | **Output variables** | `replies`: A list of replies of the LLM to the input chat |
-| **API reference** | [Generators](/reference/generators-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -49,6 +49,12 @@ This Generator supports [streaming](guides-to-generators/choosing-the-right-gene
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPIChatGenerator`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 ### On its own
 
 #### Using Serverless Inference API (Inference Providers) - Free Tier Available
@@ -59,10 +65,14 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Generator expects the `model` in `api_params`. It's also recommended to specify a `provider` for better performance and reliability.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 messages = [
     ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
@@ -93,7 +103,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Generator expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack.utils import Secret
 
@@ -117,10 +129,14 @@ print(result)
 You can also use this component with multimodal models that support both text and image input:
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage, ImageContent
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 # Create an image from file path, URL, or base64
 image = ImageContent.from_file_path("path/to/your/image.jpg")
@@ -163,7 +179,9 @@ For more information, refer to the [official TGI repository](https://github.com/
 The Generator expects the `url` of your TGI instance in `api_params`.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 
 messages = [
@@ -184,11 +202,15 @@ print(result)
 
 ```python
 from haystack.components.builders import ChatPromptBuilder
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack import Pipeline
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 # no parameter init, we don't use any runtime template variables
 prompt_builder = ChatPromptBuilder()
diff --git a/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx b/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
index 29aae96538..d35f8ef3c3 100644
--- a/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
+++ b/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx
@@ -17,9 +17,9 @@ Use this component to compute document embeddings using various Hugging Face API
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.  <br /> <br />`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `documents`: A list of documents to be embedded |
 | **Output variables** | `documents`: A list of documents to be embedded (enriched with embeddings) |
-| **API reference** | [Embedders](/reference/embedders-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -43,8 +43,14 @@ The token is needed:
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPIDocumentEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 Similarly to other Document Embedders, this component allows adding prefixes (and postfixes) to include instruction and embedding metadata.
-For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapidocumentembedder).
+For more fine-grained details, refer to the component’s [API reference](/reference/integrations-huggingface-api#huggingfaceapidocumentembedder).
 
 ### On its own
 
@@ -56,7 +62,9 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Embedder expects the `model` in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.utils import Secret
 from haystack.dataclasses import Document
 
@@ -84,7 +92,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Embedder expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.utils import Secret
 from haystack.dataclasses import Document
 
@@ -123,7 +133,9 @@ For more information, refer to the [official TEI repository](https://github.com/
 The Embedder expects the `url` of your TEI instance in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.dataclasses import Document
 
 doc = Document(content="I love pizza!")
@@ -145,38 +157,53 @@ print(result["documents"][0].embedding)
 from haystack import Document
 from haystack import Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
-from haystack.components.embedders import HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+    HuggingFaceAPIDocumentEmbedder,
+)
 from haystack.components.writers import DocumentWriter
 from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
 
 document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
 
-documents = [Document(content="My name is Wolfgang and I live in Berlin"),
-             Document(content="I saw a black horse running"),
-             Document(content="Germany has many big cities")]
+documents = [
+    Document(content="My name is Wolfgang and I live in Berlin"),
+    Document(content="I saw a black horse running"),
+    Document(content="Germany has many big cities"),
+]
 
-document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
-				                                           api_params={"model": "BAAI/bge-small-en-v1.5"})
+document_embedder = HuggingFaceAPIDocumentEmbedder(
+    api_type="serverless_inference_api",
+    api_params={"model": "BAAI/bge-small-en-v1.5"},
+)
 
 indexing_pipeline = Pipeline()
 indexing_pipeline.add_component("document_embedder", document_embedder)
-indexing_pipeline.add_component("doc_writer", DocumentWriter(document_store=document_store)
+indexing_pipeline.add_component(
+    "doc_writer",
+    DocumentWriter(document_store=document_store),
+)
 indexing_pipeline.connect("document_embedder", "doc_writer")
 indexing_pipeline.run({"document_embedder": {"documents": documents}})
 
-text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
-                                           api_params={"model": "BAAI/bge-small-en-v1.5"})
+text_embedder = HuggingFaceAPITextEmbedder(
+    api_type="serverless_inference_api",
+    api_params={"model": "BAAI/bge-small-en-v1.5"},
+)
 
 query_pipeline = Pipeline()
 query_pipeline.add_component("text_embedder", text_embedder)
-query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
+query_pipeline.add_component(
+    "retriever",
+    InMemoryEmbeddingRetriever(document_store=document_store),
+)
 query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
 
 query = "Who lives in Berlin?"
 
-result = query_pipeline.run({"text_embedder":{"text": query}})
+result = query_pipeline.run({"text_embedder": {"text": query}})
 
-print(result['retriever']['documents'][0])
+print(result["retriever"]["documents"][0])
 
 # Document(id=..., content: 'My name is Wolfgang and I live in Berlin', ...)
 ```
diff --git a/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapitextembedder.mdx b/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapitextembedder.mdx
index 0e7f68ff29..436c92512b 100644
--- a/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapitextembedder.mdx
+++ b/docs-website/versioned_docs/version-2.30/pipeline-components/embedders/huggingfaceapitextembedder.mdx
@@ -17,9 +17,9 @@ Use this component to embed strings using various Hugging Face APIs.
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.  <br /> <br />`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `text`: A string |
 | **Output variables** | `embedding`: A list of float numbers |
-| **API reference** | [Embedders](/reference/embedders-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_text_embedder.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -43,8 +43,14 @@ The token is needed:
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPITextEmbedder`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 Similarly to other text Embedders, this component allows adding prefixes (and postfixes) to include instructions.
-For more fine-grained details, refer to the component’s [API reference](/reference/embedders-api#huggingfaceapitextembedder).
+For more fine-grained details, refer to the component’s [API reference](/reference/integrations-huggingface-api#huggingfaceapitextembedder).
 
 ### On its own
 
@@ -56,7 +62,9 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Embedder expects the `model` in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -80,7 +88,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Embedder expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -115,7 +125,9 @@ For more information, refer to the [official TEI repository](https://github.com/
 The Embedder expects the `url` of your TEI instance in `api_params`.
 
 ```python
-from haystack.components.embedders import HuggingFaceAPITextEmbedder
+from haystack_integrations.components.embedders.huggingface_api import (
+    HuggingFaceAPITextEmbedder,
+)
 from haystack.utils import Secret
 
 text_embedder = HuggingFaceAPITextEmbedder(
@@ -134,7 +146,7 @@ print(text_embedder.run("I love pizza!"))
 from haystack import Document
 from haystack import Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
-from haystack.components.embedders import (
+from haystack_integrations.components.embedders.huggingface_api import (
     HuggingFaceAPITextEmbedder,
     HuggingFaceAPIDocumentEmbedder,
 )
diff --git a/docs-website/versioned_docs/version-2.30/pipeline-components/generators/huggingfaceapichatgenerator.mdx b/docs-website/versioned_docs/version-2.30/pipeline-components/generators/huggingfaceapichatgenerator.mdx
index debaa6376f..343a7f7bf3 100644
--- a/docs-website/versioned_docs/version-2.30/pipeline-components/generators/huggingfaceapichatgenerator.mdx
+++ b/docs-website/versioned_docs/version-2.30/pipeline-components/generators/huggingfaceapichatgenerator.mdx
@@ -17,9 +17,9 @@ This generator enables chat completion using various Hugging Face APIs.
 | **Mandatory init variables** | `api_type`: The type of Hugging Face API to use  <br /> <br />`api_params`: A dictionary with one of the following keys:  <br /> <br />- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`.**OR** - `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or `TEXT_EMBEDDINGS_INFERENCE`.`token`: The Hugging Face API token. Can be set with `HF_API_TOKEN` or `HF_TOKEN` env var. |
 | **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat or a plain string |
 | **Output variables** | `replies`: A list of replies of the LLM to the input chat |
-| **API reference** | [Generators](/reference/generators-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/hugging_face_api.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -49,6 +49,12 @@ This Generator supports [streaming](guides-to-generators/choosing-the-right-gene
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceAPIChatGenerator`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 ### On its own
 
 #### Using Serverless Inference API (Inference Providers) - Free Tier Available
@@ -59,10 +65,14 @@ To use this API, you need a [free Hugging Face token](https://huggingface.co/set
 The Generator expects the `model` in `api_params`. It's also recommended to specify a `provider` for better performance and reliability.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 messages = [
     ChatMessage.from_system("\\nYou are a helpful, respectful and honest assistant"),
@@ -93,7 +103,9 @@ Additionally, in this case, you need to provide your Hugging Face token.
 The Generator expects the `url` of your endpoint in `api_params`.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack.utils import Secret
 
@@ -117,10 +129,14 @@ print(result)
 You can also use this component with multimodal models that support both text and image input:
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage, ImageContent
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 # Create an image from file path, URL, or base64
 image = ImageContent.from_file_path("path/to/your/image.jpg")
@@ -163,7 +179,9 @@ For more information, refer to the [official TGI repository](https://github.com/
 The Generator expects the `url` of your TGI instance in `api_params`.
 
 ```python
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 
 messages = [
@@ -184,11 +202,15 @@ print(result)
 
 ```python
 from haystack.components.builders import ChatPromptBuilder
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack_integrations.components.generators.huggingface_api import (
+    HuggingFaceAPIChatGenerator,
+)
 from haystack.dataclasses import ChatMessage
 from haystack import Pipeline
 from haystack.utils import Secret
-from haystack.utils.hf import HFGenerationAPIType
+from haystack_integrations.components.common.huggingface_api.utils import (
+    HFGenerationAPIType,
+)
 
 # no parameter init, we don't use any runtime template variables
 prompt_builder = ChatPromptBuilder()
diff --git a/haystack/components/embedders/hugging_face_api_document_embedder.py b/haystack/components/embedders/hugging_face_api_document_embedder.py
index 0b2951f8ed..9718e40e71 100644
--- a/haystack/components/embedders/hugging_face_api_document_embedder.py
+++ b/haystack/components/embedders/hugging_face_api_document_embedder.py
@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import warnings
 from asyncio import Semaphore, gather
 from dataclasses import replace
 from itertools import chain
@@ -144,6 +145,15 @@ def __init__(
             The maximum number of requests that should be allowed to run concurrently.
             This parameter is only used in the `run_async` method.
         """
+        warnings.warn(
+            "`HuggingFaceAPIDocumentEmbedder` will be removed from Haystack in version 3.0, as it is moving to "
+            "the `huggingface-api-haystack` package. To continue using it, install that package with "
+            "`pip install huggingface-api-haystack` and update your import to "
+            "`from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder`.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         huggingface_hub_import.check()
 
         if isinstance(api_type, str):
diff --git a/haystack/components/embedders/hugging_face_api_text_embedder.py b/haystack/components/embedders/hugging_face_api_text_embedder.py
index 5eb45a8c73..7f758ca267 100644
--- a/haystack/components/embedders/hugging_face_api_text_embedder.py
+++ b/haystack/components/embedders/hugging_face_api_text_embedder.py
@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import warnings
 from typing import Any
 
 from haystack import component, default_from_dict, default_to_dict, logging
@@ -109,6 +110,15 @@ def __init__(
             if the backend uses Text Embeddings Inference.
             If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored.
         """
+        warnings.warn(
+            "`HuggingFaceAPITextEmbedder` will be removed from Haystack in version 3.0, as it is moving to "
+            "the `huggingface-api-haystack` package. To continue using it, install that package with "
+            "`pip install huggingface-api-haystack` and update your import to "
+            "`from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder`.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         huggingface_hub_import.check()
 
         if isinstance(api_type, str):
diff --git a/haystack/components/generators/chat/hugging_face_api.py b/haystack/components/generators/chat/hugging_face_api.py
index a245cd69c4..612d6ebd6a 100644
--- a/haystack/components/generators/chat/hugging_face_api.py
+++ b/haystack/components/generators/chat/hugging_face_api.py
@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import json
+import warnings
 from collections.abc import AsyncIterable, Iterable
 from datetime import datetime
 from typing import Any, Union
@@ -391,6 +392,14 @@ def __init__(
             Support for tools in the Hugging Face API and TGI is not yet fully refined and you may experience
             unexpected behavior.
         """
+        warnings.warn(
+            "`HuggingFaceAPIChatGenerator` will be removed from Haystack in version 3.0, as it is moving to "
+            "the `huggingface-api-haystack` package. To continue using it, install that package with "
+            "`pip install huggingface-api-haystack` and update your import to "
+            "`from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator`.",
+            FutureWarning,
+            stacklevel=2,
+        )
 
         huggingface_hub_import.check()
 
diff --git a/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml b/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml
new file mode 100644
index 0000000000..944a8f11e6
--- /dev/null
+++ b/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml
@@ -0,0 +1,13 @@
+---
+deprecations:
+  - |
+    ``HuggingFaceAPIChatGenerator``, ``HuggingFaceAPITextEmbedder``, and ``HuggingFaceAPIDocumentEmbedder`` are
+    deprecated and will be removed from Haystack in version 3.0. They are moving to the
+    ``huggingface-api-haystack`` package. To continue using them, install the package with
+    ``pip install huggingface-api-haystack`` and update your imports as follows:
+
+    .. code-block:: python
+
+        from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
+        from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
+        from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder

From 84a00f4ab7817a248a4acb5fa2bce29a3422a895 Mon Sep 17 00:00:00 2001
From: anakin87 <stefanofiorucci@gmail.com>
Date: Fri, 5 Jun 2026 12:37:42 +0200
Subject: [PATCH 2/2] ranker

---
 .../rankers/huggingfaceteiranker.mdx           | 18 +++++++++++++-----
 .../rankers/huggingfaceteiranker.mdx           | 18 +++++++++++++-----
 .../components/rankers/hugging_face_tei.py     | 10 ++++++++++
 ...ate-hf-api-components-d6935cc408fdcf1a.yaml |  7 ++++---
 4 files changed, 40 insertions(+), 13 deletions(-)

diff --git a/docs-website/docs/pipeline-components/rankers/huggingfaceteiranker.mdx b/docs-website/docs/pipeline-components/rankers/huggingfaceteiranker.mdx
index 9d2e7f714b..b1250d6f64 100644
--- a/docs-website/docs/pipeline-components/rankers/huggingfaceteiranker.mdx
+++ b/docs-website/docs/pipeline-components/rankers/huggingfaceteiranker.mdx
@@ -17,9 +17,9 @@ Use this component to rank documents based on their similarity to the query usin
 | **Mandatory init variables** | `url`: Base URL of the TEI reranking service (for example, "https://api.example.com"). |
 | **Mandatory run variables** | `query`: A query string  <br /> <br />`documents`: A list of document objects |
 | **Output variables** | `documents`: A grouped list of documents |
-| **API reference** | [Rankers](/reference/rankers-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/hugging_face_tei.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -38,6 +38,12 @@ Depending on your TEI server configuration, you may also require a Hugging Face
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceTEIRanker`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 ### On its own
 
 You can use `HuggingFaceTEIRanker` outside of a pipeline to order documents based on your query.
@@ -46,7 +52,7 @@ This example uses the `HuggingFaceTEIRanker` to rank two simple documents. To ru
 
 ```python
 from haystack import Document
-from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
 from haystack.utils import Secret
 
 reranker = HuggingFaceTEIRanker(
@@ -76,7 +82,9 @@ Below is an example of a pipeline that retrieves documents from an `InMemoryDocu
 from haystack import Document, Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
 from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
-from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack_integrations.components.rankers.huggingface_api import (
+    HuggingFaceTEIRanker,
+)
 
 docs = [
     Document(content="Paris is in France"),
diff --git a/docs-website/versioned_docs/version-2.30/pipeline-components/rankers/huggingfaceteiranker.mdx b/docs-website/versioned_docs/version-2.30/pipeline-components/rankers/huggingfaceteiranker.mdx
index 9d2e7f714b..b1250d6f64 100644
--- a/docs-website/versioned_docs/version-2.30/pipeline-components/rankers/huggingfaceteiranker.mdx
+++ b/docs-website/versioned_docs/version-2.30/pipeline-components/rankers/huggingfaceteiranker.mdx
@@ -17,9 +17,9 @@ Use this component to rank documents based on their similarity to the query usin
 | **Mandatory init variables** | `url`: Base URL of the TEI reranking service (for example, "https://api.example.com"). |
 | **Mandatory run variables** | `query`: A query string  <br /> <br />`documents`: A list of document objects |
 | **Output variables** | `documents`: A grouped list of documents |
-| **API reference** | [Rankers](/reference/rankers-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/rankers/hugging_face_tei.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Hugging Face API](/reference/integrations-huggingface-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/huggingface_api |
+| **Package name** | `huggingface-api-haystack` |
 
 </div>
 
@@ -38,6 +38,12 @@ Depending on your TEI server configuration, you may also require a Hugging Face
 
 ## Usage
 
+Install the `huggingface-api-haystack` package to use the `HuggingFaceTEIRanker`:
+
+```shell
+pip install huggingface-api-haystack
+```
+
 ### On its own
 
 You can use `HuggingFaceTEIRanker` outside of a pipeline to order documents based on your query.
@@ -46,7 +52,7 @@ This example uses the `HuggingFaceTEIRanker` to rank two simple documents. To ru
 
 ```python
 from haystack import Document
-from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker
 from haystack.utils import Secret
 
 reranker = HuggingFaceTEIRanker(
@@ -76,7 +82,9 @@ Below is an example of a pipeline that retrieves documents from an `InMemoryDocu
 from haystack import Document, Pipeline
 from haystack.document_stores.in_memory import InMemoryDocumentStore
 from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
-from haystack.components.rankers import HuggingFaceTEIRanker
+from haystack_integrations.components.rankers.huggingface_api import (
+    HuggingFaceTEIRanker,
+)
 
 docs = [
     Document(content="Paris is in France"),
diff --git a/haystack/components/rankers/hugging_face_tei.py b/haystack/components/rankers/hugging_face_tei.py
index 5e5957854f..cf99d39236 100644
--- a/haystack/components/rankers/hugging_face_tei.py
+++ b/haystack/components/rankers/hugging_face_tei.py
@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import warnings
 from dataclasses import replace
 from enum import Enum
 from typing import Any
@@ -87,6 +88,15 @@ def __init__(
             depending on your TEI server configuration.
             Check your HF token in your [account settings](https://huggingface.co/settings/tokens).
         """
+        warnings.warn(
+            "`HuggingFaceTEIRanker` will be removed from Haystack in version 3.0, as it is moving to "
+            "the `huggingface-api-haystack` package. To continue using it, install that package with "
+            "`pip install huggingface-api-haystack` and update your import to "
+            "`from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker`.",
+            FutureWarning,
+            stacklevel=2,
+        )
+
         self.url = url
         self.top_k = top_k
         self.timeout = timeout
diff --git a/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml b/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml
index 944a8f11e6..0ec5ec157b 100644
--- a/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml
+++ b/releasenotes/notes/deprecate-hf-api-components-d6935cc408fdcf1a.yaml
@@ -1,9 +1,9 @@
 ---
 deprecations:
   - |
-    ``HuggingFaceAPIChatGenerator``, ``HuggingFaceAPITextEmbedder``, and ``HuggingFaceAPIDocumentEmbedder`` are
-    deprecated and will be removed from Haystack in version 3.0. They are moving to the
-    ``huggingface-api-haystack`` package. To continue using them, install the package with
+    ``HuggingFaceAPIChatGenerator``, ``HuggingFaceAPITextEmbedder``, ``HuggingFaceAPIDocumentEmbedder``, and
+    ``HuggingFaceTEIRanker`` are deprecated and will be removed from Haystack in version 3.0. They are moving to
+    the ``huggingface-api-haystack`` package. To continue using them, install the package with
     ``pip install huggingface-api-haystack`` and update your imports as follows:
 
     .. code-block:: python
@@ -11,3 +11,4 @@ deprecations:
         from haystack_integrations.components.generators.huggingface_api import HuggingFaceAPIChatGenerator
         from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPIDocumentEmbedder
         from haystack_integrations.components.embedders.huggingface_api import HuggingFaceAPITextEmbedder
+        from haystack_integrations.components.rankers.huggingface_api import HuggingFaceTEIRanker