Repository: huggingface/hub-docs
Pull request #1663: [Inference Providers] How to register as a provider
Author: login: hanouticelina
Created: 2025-04-01T10:45:51Z | Merged: 2025-04-03T13:03:25Z

Closes #1664.

Copied from this [document](https://huggingface.slack.com/archives/C07KX53FZTK/p1743066129757799?thread_ts=1742574953.859619&cid=C07KX53FZTK) (internal).

TODO: 

- [x] Complete the JS integration section based on the new code structure introduced in https://github.com/huggingface/huggingface.js/pull/1315
- [x] Add a "Get in Touch" section
 

Linked issue #1664: Page: "how to be registered as a provider"?

Diff:
diff --git a/docs/inference-providers/_toctree.yml b/docs/inference-providers/_toctree.yml
index 7a11d8bec3..512708c99c 100644
--- a/docs/inference-providers/_toctree.yml
+++ b/docs/inference-providers/_toctree.yml
@@ -8,6 +8,8 @@
     title: Hub integration
   - local: security
     title: Security
+  - local: register-as-a-provider
+    title: Register as an Inference Provider
 - title: API Reference
   sections:
   - local: tasks/index
diff --git a/docs/inference-providers/index.md b/docs/inference-providers/index.md
index a27bb14452..fe6bd9c574 100644
--- a/docs/inference-providers/index.md
+++ b/docs/inference-providers/index.md
@@ -165,8 +165,8 @@ console.log(chatCompletion.choices[0].message);
 ## Next Steps
 
 In this introduction, we've covered the basics of Inference Providers. To learn more about this service, check out our guides and API Reference:
-- [Pricing and Billing](./pricing): everything you need to know about billing
+- [Pricing and Billing](./pricing): everything you need to know about billing.
 - [Hub integration](./hub-integration): how is Inference Providers integrated with the Hub?
-- [External Providers](./providers): everything about providers and how to become an official partner
-- [Hub API](./hub-api): high-level API for Inference Providers
+- [Register as an Inference Provider](./register-as-a-provider.md): everything about how to become an official partner. 
+- [Hub API](./hub-api): high-level API for Inference Providers.
 - [API Reference](./tasks/index): learn more about the parameters and task-specific settings.
diff --git a/docs/inference-providers/register-as-a-provider.md b/docs/inference-providers/register-as-a-provider.md
new file mode 100644
index 0000000000..b396e1a98c
--- /dev/null
+++ b/docs/inference-providers/register-as-a-provider.md
@@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be listed as an Inference Provider on the Hugging Face Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Register your provider server-side and provide an icon** - Reach out to us to add your provider server-side and provide your SVG icon.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Open a Pull Request in this repo (huggingface/hub-docs) to add a provider-specific page in the documentation.
+9. **Share share share** do a lot of comms so that your integration is as successful as possible!
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper (JS)
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from `BaseTextGenerationTask` and `BaseConversationalTask` respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
+
+Congratulations! You now have a JS implementation to successfully make inference calls on your infra! Time to integrate with the Hub!
+
+First step is to use the Model Mapping API to register which HF models are supported. 
+
+<Tip>
+
+To proceed with this step, we have to enable your account server-side. Make sure you have an organization on the Hub for your enterprise.
+
+</Tip>
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"]
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity, the output is grouped by task.
+
+<Tip warning={true}>
+
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly. 
+More details about the pricing structure can be found on the [pricing page](./pricing.md).
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end. 
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### Implement the provider helper (Python)
+
+Create a new file under `src/huggingface_hub/inference/_providers/{provider_name}.py` and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
+
+


Reviews:
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T15:25:57Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T15:27:15Z
user: login: Wauplin
body: Made a first pass!
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-01T16:47:32Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T08:58:47Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:07:24Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:08:54Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:14:51Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:29:45Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T09:31:00Z
user: login: SBrandeis
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T10:05:57Z
user: login: julien-c
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-02T10:59:40Z
user: login: julien-c
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-02T11:00:46Z
user: login: julien-c
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-02T11:06:49Z
user: login: julien-c
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-02T11:07:49Z
user: login: julien-c
body: looks great, i'm wondering if we should or not split into one page per section? wdyt
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-02T11:08:40Z
user: login: SBrandeis
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T11:47:03Z
user: login: SBrandeis
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T11:48:18Z
user: login: SBrandeis
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T11:48:53Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T12:46:04Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T12:57:27Z
user: login: julien-c
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-02T13:17:44Z
user: login: Wauplin
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T14:44:01Z
user: login: Wauplin
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-02T14:48:05Z
user: login: Wauplin
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T09:22:12Z
user: login: gary149
body: Nice!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T09:36:11Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T09:47:10Z
user: login: Wauplin
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T09:53:41Z
user: login: hanouticelina
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T10:16:55Z
user: login: Wauplin
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T10:29:07Z

Review comments:
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
+
+## Get in touch!
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: Not sure what to put in this section or if we should put it in the beginning of the doc instead. 
created_at: 2025-04-01T15:25:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: this section is based on the refacto implemented here https://github.com/huggingface/huggingface.js/pull/1315 (not merged yet)
created_at: 2025-04-01T15:27:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
+
+## Get in touch!
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: My initial intent was to add this at the very top of the doc page, potentially in a `<Tip>` section to say "Wanna be an Inference Provider on the Hub? Please reach out to us!". Even if we have a proper documentation, it's still best if partners contact us before working too much in the implementation details. 
created_at: 2025-04-01T16:08:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
<Tip>

If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.

</Tip>
```
created_at: 2025-04-01T16:21:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
The first step to understand the integration is to take a look at the JS inference client that lives inside the huggingface.js repo: https://github.com/huggingface/huggingface.js/tree/main/packages/inference
```

(I usually tend to prefer 1 paragraph == 1 code line => easier to review when making changes to it afterwards)

(same for the whole module)
created_at: 2025-04-01T16:23:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
This is the client that powers our Inference widgets on model pages, and is the blueprint
implementation downstream (for Python SDK, to generate code snippets, etc.).
```
created_at: 2025-04-01T16:25:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
## 1. Prerequisites
```
(nit :see_no_evil:)
created_at: 2025-04-01T16:28:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
### Implement the provider helper
```

I would keep the numbered items only for the `##` section titles. Having 2 levels of numbers is confusing IMO

(same for other section titles)
created_at: 2025-04-01T16:29:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
Create a new file under `./packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
```
created_at: 2025-04-01T16:30:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
	getResponse(response: <something else?>, outputType?: "url" | "blob"): string | Promise<Blob>{
```
created_at: 2025-04-01T16:30:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
```

(for consistency)
created_at: 2025-04-01T16:34:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
Congratulations! You now have a JS implementation to successfully make inference calls on your infra! Time to integrate with the Hub!

First step is to use the Model Mapping API to register which HF models are supported. To proceed with this step, we have to enable your account server-side. Make sure you have an organization on the Hub for your enterprise.
```
created_at: 2025-04-01T16:38:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
```

(I feel that it's kinda redundant with intro)
created_at: 2025-04-01T16:40:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: or even put the `First step is to  ...` in a Tip section => they cannot move forward without us
created_at: 2025-04-01T16:40:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: Link to billing page somewhere in that section
created_at: 2025-04-01T16:41:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: Not sure we want to mention this "as-is" in the docs
created_at: 2025-04-01T16:42:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: Maybe let's not mention that since we are slightly moving away from VCR tests
created_at: 2025-04-01T16:43:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: I would briefly mention in the introduction what we expect from them:
- Use tasks
- PR for JS client 
- Mapping
- Billing endpoint
- PR for Python client

with links to the corresponding docs
created_at: 2025-04-01T16:44:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: also: provide an icon (svg)
created_at: 2025-04-01T16:45:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: is that really true? (I haven't followed that)
created_at: 2025-04-01T16:46:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: + add documentation on their side
+ make comms!
+ as last step: add documentation page in HF docs (not done yet but we'll have 1 doc per provider)
created_at: 2025-04-01T16:47:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: 🙈 wrong copy-paste
created_at: 2025-04-02T08:58:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: agreed, I will remove it for now
created_at: 2025-04-02T09:07:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: yes I will remove that for the JS integration as well
created_at: 2025-04-02T09:08:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: instead, it seems more natural that the Tip only contains the information about the fact that we have to enable their account server-side:
```md
First step is to use the Model Mapping API to register which HF models are supported. 

<Tip>

To proceed with this step, we have to enable your account server-side. Make sure you have an organization on the Hub for your enterprise.

</Tip>
```
created_at: 2025-04-02T09:14:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: addressed [here](https://github.com/huggingface/hub-docs/pull/1663/files/6e3836097655b77f3118410d33c78888e348051b..40e7e85253a1efc73a0ddadaf6465186da16b664). 
created_at: 2025-04-02T09:29:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: I'm not sure either, cc @julien-c 
created_at: 2025-04-02T09:31:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
path: docs/inference-providers/register-as-a-provider.md
user: login: SBrandeis
body: For now it's random order, but we do want to order by usage eventually indeed
created_at: 2025-04-02T10:05:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us!
path: docs/inference-providers/register-as-a-provider.md
user: login: julien-c
body: ```suggestion
Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
```
created_at: 2025-04-02T10:59:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us!
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation** - Add documentation and do some communication on your side.
path: docs/inference-providers/register-as-a-provider.md
user: login: julien-c
body: ```suggestion
7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
```
created_at: 2025-04-02T11:00:46Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,424 @@
+# How to be registered as an inference provider on the Hub?
+
+If you'd like to be an inference provider on the Hub, you must follow the steps outlined in this guide.
+
+## 1. Requirements
+
+<Tip>
+
+If you provide inference only for LLMs and VLMs following the OpenAI API, you
+can probably skip most of this section and just open a PR on
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference to add you as a provider.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the huggingface.js repo:
+https://github.com/huggingface/huggingface.js/tree/main/packages/inference
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation for other downstream SDKs like Python's `huggingface-hub` and other tools.
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### 1. Implement the provider helper
+
+Create a new file under packages/inference/src/providers/{provider_name}.ts and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: TogetherBase64ImageGeneration, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### 2. Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+### 3. Add tests
+
+Go to [packages/inference/test/InferenceClient.spec.ts](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/InferenceClient.spec.ts) and add new tests for each task supported by your provider. 
+
+
+## 3. Model Mapping API
+
+Once you've verified the huggingface.js/inference client can call your models successfully, you
+can use our Model Mapping API.
+
+This API lets a Partner "register" that they support model X, Y or Z on HF.
+
+This enables:
+- The inference widget on corresponding model pages
+- Inference compatibility throughout the HF ecosystem (Python and JS client SDKs for instance), and any downstream tool or library
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity/DX, the output is grouped by task.
+
+<Tip warning={true}>
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+For LLM providers, a workaround some people use is to extract numbers of input and output
+tokens in the responses and multiply by a hardcoded pricing table – this is quite brittle, so we
+are reluctant to do this.
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end.
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### 1. Implement the provider helper
+Create a new file under src/huggingface_hub/inference/_providers/{provider_name}.py and copy-paste the following snippet.
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. At least one of `_prepare_payload_as_dict` or `_prepare_payload_as_bytes` must be overwritten.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern shown in fal_ai.py.
+
+For text-generation and conversational tasks, one can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in _common.py) and override the methods if needed. Examples can be found in fireworks_ai.py and together.py.
+
+```python
+from typing import Any, Dict, Optional, Union
+
+from ._common import TaskProviderHelper
+
+
+class MyNewProviderTaskProviderHelper(TaskProviderHelper):
+    def __init__(self):
+        """Define high-level parameters."""
+        super().__init__(provider=..., base_url=..., task=...)
+
+    def get_response(
+        self,
+        response: Union[bytes, Dict],
+        request_params: Optional[RequestParameters] = None,
+    ) -> Any:
+        """
+        Return the response in the expected format.
+
+        Override this method in subclasses for customized response handling."""
+        return super().get_response(response)
+
+    def _prepare_headers(self, headers: Dict, api_key: str) -> Dict:
+        """Return the headers to use for the request.
+
+        Override this method in subclasses for customized headers.
+        """
+        return super()._prepare_headers(headers, api_key)
+
+    def _prepare_route(self, mapped_model: str, api_key: str) -> str:
+        """Return the route to use for the request.
+
+        Override this method in subclasses for customized routes.
+        """
+        return super()._prepare_route(mapped_model)
+
+    def _prepare_payload_as_dict(self, inputs: Any, parameters: Dict, mapped_model: str) -> Optional[Dict]:
+        """Return the payload to use for the request, as a dict.
+
+        Override this method in subclasses for customized payloads.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_dict(inputs, parameters, mapped_model)
+
+    def _prepare_payload_as_bytes(
+        self, inputs: Any, parameters: Dict, mapped_model: str, extra_payload: Optional[Dict]
+    ) -> Optional[bytes]:
+        """Return the body to use for the request, as bytes.
+
+        Override this method in subclasses for customized body data.
+        Only one of `_prepare_payload_as_dict` and `_prepare_payload_as_bytes` should return a value.
+        """
+        return super()._prepare_payload_as_bytes(inputs, parameters, mapped_model, extra_payload)
+```
+
+### 2. Register the Provider
+- Go to [src/huggingface_hub/inference/_providers/__init__.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_providers/__init__.py) and add your provider to `PROVIDER_T` and `PROVIDERS`. Please try to respect alphabetical order. 
+- Go to [src/huggingface_hub/inference/_client.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/inference/_client.py) and update docstring in `InferenceClient.__init__` to document your provider.
+
+### 3. Add tests
+- Go to [tests/test_inference_providers.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_providers.py) and add static tests for overridden methods.
+- Go to [tests/test_inference_client.py](https://github.com/huggingface/huggingface_hub/blob/main/tests/test_inference_client.py) and add VCR tests:
+
+
+    a. Add an entry to `_RECOMMENDED_MODELS_FOR_VCR` at the top of the test module. This contains a mapping task <> test model. model-id must be the HF model id.
+    ```python
+    _RECOMMENDED_MODELS_FOR_VCR = {
+        "your-provider": {
+            "task": "model-id",
+            ...
+        },
+        ...
+    }
+    ```
+
+    b. Set up authentication: To record VCR cassettes, you'll need authentication:
+    If you are a member of the provider organization (e.g., Replicate organization: https://huggingface.co/replicate), you can set the HF_INFERENCE_TEST_TOKEN environment variable with your HF token:
+
+    ```bash
+    export HF_INFERENCE_TEST_TOKEN="your-hf-token"
+    ```
+    
+    If you're not a member but the provider is officially released on the Hub, you can set the HF_INFERENCE_TEST_TOKEN environment variable as above. If you don't have enough inference credits, we can help you record the VCR cassettes.
+
+    c. Record and commit tests
+    Run the tests for your provider:
+    ```bash
+    pytest tests/test_inference_client.py -k <provider>
+    ```
+
+    d. Commit the generated VCR cassettes with your PR.
+
+
+## FAQ
+
+**Question:** By default, in which order do we list providers in the settings page?
+
+**Answer:** The default sort is by total number of requests routed by HF over the last 7 days. This order defines which provider will be used in priority by the widget on the model page (but the user's order takes precedence).
path: docs/inference-providers/register-as-a-provider.md
user: login: julien-c
body: yes we can keep this in the doc anyways
created_at: 2025-04-02T11:06:48Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us!
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation** - Add documentation and do some communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
path: docs/inference-providers/register-as-a-provider.md
user: login: julien-c
body: ```suggestion
8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
9. **Share share share** do a lot of comms so that your integration is as successful as possible!
```
created_at: 2025-04-02T11:07:49Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
path: docs/inference-providers/register-as-a-provider.md
user: login: SBrandeis
body: An additional step here is to get in touch with us to add the provider to moon-landing and map to the organization
created_at: 2025-04-02T11:47:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
path: docs/inference-providers/register-as-a-provider.md
user: login: SBrandeis
body: Maybe we should provide some programmatic spec like an OpenAPI document for the APIs (model mapping API + billing API)
created_at: 2025-04-02T11:48:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
+
+Congratulations! You now have a JS implementation to successfully make inference calls on your infra! Time to integrate with the Hub!
+
+First step is to use the Model Mapping API to register which HF models are supported. 
+
+<Tip>
+
+To proceed with this step, we have to enable your account server-side. Make sure you have an organization on the Hub for your enterprise.
+
+</Tip>
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"] // (both can't be defined at the same time)
path: docs/inference-providers/register-as-a-provider.md
user: login: SBrandeis
body: ```suggestion
    "hfFilter": ["string"]
```
created_at: 2025-04-02T11:48:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: where should we put the OpenAPI specs yaml files?
created_at: 2025-04-02T12:46:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: we added a Tip in the Model Mapping API section for that: https://github.com/huggingface/hub-docs/blob/549ecd03e9f5b818e45126f20115d0e95e79a0eb/docs/inference-providers/register-as-a-provider.md?plain=1#L130

but I'm okay to add a specific section for that, wdyt? 
created_at: 2025-04-02T12:57:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
path: docs/inference-providers/register-as-a-provider.md
user: login: julien-c
body: at some point but maybe not right now:)
created_at: 2025-04-02T13:17:44Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
+9. **Share share share** do a lot of comms so that your integration is as successful as possible!
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
### Implement the provider helper (JS)
```

otherwise the anchor on the page is the same as the Python one (`#implement-the-provider-helper`)
created_at: 2025-04-02T14:43:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
+9. **Share share share** do a lot of comms so that your integration is as successful as possible!
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
+
+
+## 3. Model Mapping API
+
+Congratulations! You now have a JS implementation to successfully make inference calls on your infra! Time to integrate with the Hub!
+
+First step is to use the Model Mapping API to register which HF models are supported. 
+
+<Tip>
+
+To proceed with this step, we have to enable your account server-side. Make sure you have an organization on the Hub for your enterprise.
+
+</Tip>
+
+### Register a mapping item
+
+```http
+POST /api/partners/{provider}/models
+```
+Create a new mapping item, with the following body (JSON-encoded):
+
+```json
+{
+    "task": "WidgetType", // required
+    "hfModel": "string", // required: the name of the model on HF: namespace/model-name
+    "providerModel": "string", // required: the partner's "model id" i.e. id on your side
+    "status": "live" | "staging" // Optional: defaults to "staging". "staging" models are only available to members of the partner's org, then you switch them to "live" when they're ready to go live
+}
+```
+
+- `task`, also known as `pipeline_tag` in the HF ecosystem, is the type of model / type of API
+(examples: "text-to-image", "text-generation", but you should use "conversational" for chat models)
+- `hfModel` is the model id on the Hub's side.
+- `providerModel` is the model id on your side (can be the same or different).
+
+In the future, we will add support for a new parameter (ping us if it's important to you now):
+```json
+{
+    "hfFilter": ["string"]
+    // ^Power user move: register a "tag" slice of HF in one go.
+    // Example: tag == "base_model:adapter:black-forest-labs/FLUX.1-dev" for all Flux-dev LoRAs
+}
+```
+#### Authentication
+
+You need to be in the _provider_ Hub organization (e.g. https://huggingface.co/togethercomputer
+for TogetherAI) with **Write** permissions to be able to access this endpoint.
+
+#### Validation
+
+The endpoint validates that:
+- `hfModel` is indeed of `pipeline_tag == task` OR `task` is "conversational" and the model is
+compatible (i.e. the `pipeline_tag` is either "text-generation" or "image-text-to-text" AND the model is tagged as "conversational").
+- (in the future) we auto-test that the Partner's API successfully responds to a
+huggingface.js/inference call of the corresponding task i.e. the API specs are valid.
+
+### Delete a mapping item
+
+```http
+DELETE /api/partners/{provider}/models?hfModel=namespace/model-name
+```
+
+### Update a mapping item's status
+
+Call this HTTP PUT endpoint:
+
+```http
+PUT /api/partners/{provider}/models/status
+```
+
+With the following body (JSON-encoded):
+
+```json
+{
+    "hfModel": "namespace/model-name", // The name of the model on HF
+    "status": "live" | "staging" // The new status, one of "staging" or "live"
+}   
+```
+
+### List the whole mapping
+
+```http
+GET /api/partners/{provider}/models?status=staging|live
+```
+This gets all mapping items from the DB. For clarity, the output is grouped by task.
+
+<Tip warning={true}>
+
+This is publicly accessible. It's useful to be transparent by default and it helps debug client SDKs, etc.
+
+</Tip>
+
+Here is an example of response:
+
+```json
+{
+    "text-to-image": {
+        "black-forest-labs/FLUX.1-Canny-dev": {
+            "providerId": "black-forest-labs/FLUX.1-canny",
+            "status": "live"
+        },
+        "black-forest-labs/FLUX.1-Depth-dev": {
+            "providerId": "black-forest-labs/FLUX.1-depth",
+            "status": "live"
+        }
+    },
+    "conversational": {
+        "deepseek-ai/DeepSeek-R1": {
+            "providerId": "deepseek-ai/DeepSeek-R1",
+            "status": "live"
+        }
+    },
+    "text-generation": {
+        "meta-llama/Llama-2-70b-hf": {
+            "providerId": "meta-llama/Llama-2-70b-hf",
+            "status": "live"
+        },
+        "mistralai/Mixtral-8x7B-v0.1": {
+            "providerId": "mistralai/Mixtral-8x7B-v0.1",
+            "status": "live"
+        }
+    }
+}
+```
+
+## 4. Billing
+
+For routed requests (see figure below), i.e. when users authenticate via HF, our intent is that
+our users only pay the standard provider API rates. There's no additional markup from us, we
+just pass through the provider costs directly. 
+More details about the pricing structure can be found on the [pricing page](./pricing.md).
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/types_of_billing.png"/>
+</div> 
+
+
+We propose an easier way to figure out this cost and charge it to our users, by asking you to
+provide the cost for each request via an HTTP API you host on your end. 
+
+### HTTP API Specs
+
+We ask that you expose an API that supports a HTTP POST request.
+The body of the request is a JSON-encoded object containing a list of request IDs for which we
+request the cost.
+
+```http
+POST {your URL here}
+Content-Type: application/json
+
+{
+    "requestIds": [
+        "deadbeef0",
+        "deadbeef1",
+        "deadbeef2",
+        "deadbeef3"
+    ]
+}
+```
+
+The response is also JSON-encoded. The response contains an array of objects specifying the
+request's ID and its cost in nano-USD (10^-9 USD).
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "requests": [
+        { "requestId": "deadbeef0", "costNanoUsd": 100 },
+        { "requestId": "deadbeef1", "costNanoUsd": 100 },
+        { "requestId": "deadbeef2", "costNanoUsd": 100 },
+        { "requestId": "deadbeef3", "costNanoUsd": 100 }
+    ]
+}
+```
+
+### Price Unit
+
+We require the price to be an **integer** number of **nano-USDs** (10^-9 USD).
+
+### How to define the request ID
+
+For each request/generation you serve, you should define a unique request (or response) ID,
+and provide it as a response Header. We will use this ID as the request ID for the billing API
+above.
+
+As part of those requirements, please let us know your Header name. If you don't already have one, we suggest the `Inference-Id` name for instance, and it should contain a UUID character string.
+
+**Example**: Defining an `Inference-Id` header in your inference response.
+
+```http
+POST /v1/chat/completions
+Content-Type: application/json
+[request headers]
+[request body]
+------
+HTTP/1.1 200 OK
+Content-Type: application/json
+[other request headers]
+Inference-Id: unique-id-00131
+[response body]
+```
+
+## 5. Python client integration
+
+<Tip>
+
+Before adding a new provider to the `huggingface_hub` Python library, make sure that all the previous steps have been completed and everything is working on the Hub. Support in the Python library comes as a second step. 
+
+</Tip>
+
+### Implement the provider helper
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
### Implement the provider helper (Python)
```

(see above)
created_at: 2025-04-02T14:43:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
+9. **Share share share** do a lot of comms so that your integration is as successful as possible!
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper (JS)
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: ```suggestion
For text-generation and conversational tasks, you can just inherit from `BaseTextGenerationTask` and `BaseConversationalTask` respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
```
created_at: 2025-04-02T14:46:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
path: docs/inference-providers/register-as-a-provider.md
user: login: gary149
body: ```suggestion
Want to be listed as an Inference Provider on the Hugging Face Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
```
created_at: 2025-04-03T09:32:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
path: docs/inference-providers/register-as-a-provider.md
user: login: gary149
body: where?
created_at: 2025-04-03T09:32:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
path: docs/inference-providers/register-as-a-provider.md
user: login: gary149
body: ```suggestion
8. **Add a documentation page** - Open a Pull Request in this repo (huggingface/hub-docs) to add a provider-specific page in the documentation.
```
created_at: 2025-04-03T09:34:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page here** - Add a provider-specific page in the Hub documentation.
+9. **Share share share** do a lot of comms so that your integration is as successful as possible!
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
path: docs/inference-providers/register-as-a-provider.md
user: login: gary149
body: nice 👍 
created_at: 2025-04-03T09:35:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: maybe we can replace it with "Reach out to us to add your provider server-side and provide your SVG icon" ?
created_at: 2025-04-03T09:47:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,411 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49).
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
path: docs/inference-providers/register-as-a-provider.md
user: login: Wauplin
body: (I do think that at some point the SVGs should be in inference.js instead of moon-landing but for now agree with your suggestion)
created_at: 2025-04-03T09:53:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,410 @@
+# How to be registered as an inference provider on the Hub?
+
+<Tip>
+
+Want to be an Inference Provider on the Hub? Please reach out to us on social networks or [here on the Hub](https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49)
+
+</Tip>
+
+This guide details the steps for registering as an inference provider on the Hub and provides implementation guidance.
+
+1. **Implement standard task APIs** - Follow our task API schemas for compatibility (see [Prerequisites](#1-prerequisites)).
+2. **Submit a PR for JS client integration** - Add your provider to [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) (see [JS Client Integration](#2-js-client-integration)).
+3. **Register model mappings** - Use our Model Mapping API to link your models to Hub models (see [Model Mapping API](#3-model-mapping-api)).
+4. **Implement a billing endpoint** - Provide an API for billing (see [Billing](#4-billing)).
+5. **Submit a PR for Python client integration** - Add your provider to [huggingface_hub](https://github.com/huggingface/huggingface_hub) (see [Python client integration](#5-python-client-integration)).
+6. **Provide an icon** - Submit an SVG icon for your provider.
+7. **Create documentation on your side** - Add documentation and do a lot of communication on your side.
+8. **Add a documentation page** - Add a provider-specific page in the Hub documentation.
+
+
+## 1. Prerequisites
+
+<Tip>
+
+If your implementation strictly follows the OpenAI API for LLMs and VLMs, you may be able to skip most of this section. In that case, simply open a PR on [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) to register.
+
+</Tip>
+
+The first step to understand the integration is to take a look at the JS inference client that lives
+inside the [huggingface.js](https://github.com/huggingface/huggingface.js/tree/main/packages/inference) repo.
+
+This is the client that powers our Inference widgets on model pages, and is the blueprint
+implementation downstream (for Python SDK, to generate code snippets, etc.).
+
+
+### What is a Task 
+
+You will see that inference methods (`textToImage`, `chatCompletion`, etc.) have names that closely
+mirror the task names. A task, also known as `pipeline_tag` in the HF ecosystem, is the type of
+model (basically which types of inputs and outputs the model has), for instance "text-generation"
+or "text-to-image". It is indicated prominently on model pages, here:
+
+<div class="flex justify-center">
+    <picture>
+        <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-light.png">
+        <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/inference-providers/pipeline-tag-on-model-page-dark.png">
+    </picture>
+</div>
+
+The list of all possible tasks can be found at https://huggingface.co/tasks and the list of JS method names is documented in the README at https://github.com/huggingface/huggingface.js/tree/main/packages/inference.
+
+<Tip>
+
+Note that `chatCompletion` is an exception as it is not a pipeline_tag, per se. Instead, it
+includes models with either `pipeline_tag="text-generation"` or `pipeline_tag="image-text-to-text"`
+which are tagged as "conversational".
+
+</Tip>
+
+
+### Task API schema
+
+For each task type, we enforce an API schema to make it easier for end users to use different
+models interchangeably. To be compatible, your third-party API must adhere to a "standard" shape API we expect on HF model pages for each pipeline task type.
+
+This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be
+more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there
+exists no standard API.
+
+For example, you can find the expected schema for Text to Speech here: [https://github.com/huggingface/huggingface.js/packages/src/tasks/text-to-speech/spec/input.json#L4](https://github.com/huggingface/huggingface.js/blob/0a690a14d52041a872dc103846225603599f4a33/packages/tasks/src/tasks/text-to-speech/spec/input.json#L4), and similarly for other supported tasks. If your API for a given task is different from HF's, it is not an issue: you can tweak the code in `huggingface.js` to be able to call your models, i.e., provide some kind of "translation" of parameter names and output names. However, API specs should not be model-specific, only task-specific. Run the JS code and add some [tests](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/test/HfInference.spec.ts) to make sure it works well. We can help with this step!
+
+## 2. JS Client Integration
+
+Before proceeding with the next steps, ensure you've implemented the necessary code to integrate with the JS client and thoroughly tested your implementation. Here are the steps to follow:
+
+### Implement the provider helper
+
+Create a new file under `packages/inference/src/providers/{provider_name}.ts` and copy-paste the following snippet.
+
+```ts
+import { TaskProviderHelper } from "./providerHelper";
+
+export class MyNewProviderTask extends TaskProviderHelper {
+
+	constructor() {
+		super("your-provider-name", "your-api-base-url", "task-name");
+	}
+
+    override prepareHeaders(params: HeaderParams, binary: boolean): Record<string, string> {
+        // Override the headers to use for the request.
+        return super.prepareHeaders(params, binary);
+    }
+
+	makeRoute(params: UrlParams): string {
+        // Return the route to use for the request. e.g. /v1/chat/completions route is commonly use for chat completion.
+		throw new Error("Needs to be implemented");
+	}
+
+	preparePayload(params: BodyParams): Record<string, unknown> {
+        // Return the payload to use for the request, as a dict.
+		throw new Error("Needs to be implemented");
+	}
+
+	getResponse(response: unknown, outputType?: "url" | "blob"): string | Promise<Blob>{
+		// Return the response in the expected format.
+        throw new Error("Needs to be implemented");
+    }
+}
+```
+
+Implement the methods that require custom handling. Check out the base implementation to check default behavior. If you don't need to override a method, just remove it. You have to define at least `makeRoute`, `preparePayload` and `getResponse`.
+
+If the provider supports multiple tasks that require different implementations, create dedicated subclasses for each task, following the pattern used in the existing providers implementation, e.g. [Together AI provider implementation](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/together.ts).
+
+For text-generation and conversational tasks, you can just inherit from BaseTextGenerationTask and BaseConversationalTask respectively (defined in [providerHelper.ts]((https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/providerHelper.ts))) and override the methods if needed. Examples can be found in [Cerebras](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/cerebras.ts) or [Fireworks](https://github.com/huggingface/huggingface.js/blob/main/packages/inference/src/providers/fireworks.ts) provider implementations.
+
+### Register the provider
+
+Go to [packages/inference/src/lib/getProviderHelper.ts](https://github.com/huggingface/huggingface.js//blob/main/packages/inference/src/lib/getProviderHelper.ts) and add your provider to `PROVIDERS`. Please try to respect alphabetical order. 
path: docs/inference-providers/register-as-a-provider.md
user: login: hanouticelina
body: I've added in the introduction a "Reach out to us to add your provider server-side and provide your SVG icon" step just after the JS integration https://github.com/huggingface/hub-docs/pull/1663/commits/a179888a33ea8858aa982c49172203865cd05f6f 
created_at: 2025-04-03T10:16:55Z
author_association: CONTRIBUTOR

PR comments:
user: login: HuggingFaceDocBuilderDev
created_at: 2025-04-01T10:47:15Z
body: The docs for this PR live [here](https://moon-ci-docs.huggingface.co/docs/api-inference/pr_1663). All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.
author_association: NONE
user: login: hanouticelina
created_at: 2025-04-01T15:20:26Z
body: I don't understand why the build of the PR doc is failing, I may need some help here cc @mishig25 if you have an idea

EDIT: it seems fixed now 🤷‍♀️ 
author_association: CONTRIBUTOR
user: login: Wauplin
created_at: 2025-04-02T14:42:27Z
body: PR docs page: https://moon-ci-docs.huggingface.co/docs/inference-providers/pr_1663/en/register-as-a-provider
(Bot comment is broken)
author_association: CONTRIBUTOR
user: login: hanouticelina
created_at: 2025-04-03T13:03:19Z
body: merging!
author_association: CONTRIBUTOR