@huggingface/inference 3.14.0 → 4.0.0

package/dist/esm/providers/together.js

@@ -1,6 +1,6 @@
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
 import { omit } from "../utils/omit.js";
 import { BaseConversationalTask, BaseTextGenerationTask, TaskProviderHelper, } from "./providerHelper.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 const TOGETHER_API_BASE_URL = "https://api.together.xyz";
 export class TogetherConversationalTask extends BaseConversationalTask {
     constructor() {
@@ -28,7 +28,7 @@ export class TogetherTextGenerationTask extends BaseTextGenerationTask {
                 generated_text: completion.text,
             };
         }
-        throw new InferenceOutputError("Expected Together text generation response format");
+        throw new InferenceClientProviderOutputError("Received malformed response from Together text generation API");
     }
 }
 export class TogetherTextToImageTask extends TaskProviderHelper {
@@ -60,6 +60,6 @@ export class TogetherTextToImageTask extends TaskProviderHelper {
             }
             return fetch(`data:image/jpeg;base64,${base64Data}`).then((res) => res.blob());
         }
-        throw new InferenceOutputError("Expected Together text-to-image response format");
+        throw new InferenceClientProviderOutputError("Received malformed response from Together text-to-image API");
     }
 }

package/dist/esm/tasks/audio/automaticSpeechRecognition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automaticSpeechRecognition.d.ts","sourceRoot":"","sources":["../../../../src/tasks/audio/automaticSpeechRecognition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAC;AAI5G,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,CAAC,+BAA+B,GAAG,gBAAgB,CAAC,CAAC;AAC7G;;;GAGG;AACH,wBAAsB,0BAA0B,CAC/C,IAAI,EAAE,8BAA8B,EACpC,OAAO,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gCAAgC,CAAC,CAa3C"}
+{"version":3,"file":"automaticSpeechRecognition.d.ts","sourceRoot":"","sources":["../../../../src/tasks/audio/automaticSpeechRecognition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAC;AAG5G,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,CAAC,+BAA+B,GAAG,gBAAgB,CAAC,CAAC;AAC7G;;;GAGG;AACH,wBAAsB,0BAA0B,CAC/C,IAAI,EAAE,8BAA8B,EACpC,OAAO,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,gCAAgC,CAAC,CAa3C"}

package/dist/esm/tasks/audio/automaticSpeechRecognition.js

@@ -1,7 +1,7 @@
 import { resolveProvider } from "../../lib/getInferenceProviderMapping.js";
 import { getProviderHelper } from "../../lib/getProviderHelper.js";
-import { InferenceOutputError } from "../../lib/InferenceOutputError.js";
 import { innerRequest } from "../../utils/request.js";
+import { InferenceClientProviderOutputError } from "../../errors.js";
 /**
  * This task reads some audio input and outputs the said words within the audio files.
  * Recommended model (english language): facebook/wav2vec2-large-960h-lv60-self
@@ -16,7 +16,7 @@ export async function automaticSpeechRecognition(args, options) {
     });
     const isValidOutput = typeof res?.text === "string";
     if (!isValidOutput) {
-        throw new InferenceOutputError("Expected {text: string}");
+        throw new InferenceClientProviderOutputError("Received malformed response from automatic-speech-recognition API");
     }
     return providerHelper.getResponse(res);
 }

package/dist/esm/utils/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/utils/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAIvE,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,cAAc,EAAE;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,WAAW,CAAC;KAClB,CAAC;CACF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EACnC,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,EACpD,OAAO,CAAC,EAAE,OAAO,GAAG;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GACC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAoC7B;AAED;;GAEG;AACH,wBAAuB,qBAAqB,CAAC,CAAC,EAC7C,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,EACpD,OAAO,CAAC,EAAE,OAAO,GAAG;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GACC,cAAc,CAAC,CAAC,CAAC,CAuFnB"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/utils/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMvE,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,cAAc,EAAE;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,WAAW,CAAC;KAClB,CAAC;CACF;AAaD;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EACnC,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,EACpD,OAAO,CAAC,EAAE,OAAO,GAAG;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GACC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAwE7B;AAED;;GAEG;AACH,wBAAuB,qBAAqB,CAAC,CAAC,EAC7C,IAAI,EAAE,WAAW,EACjB,cAAc,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,EACpD,OAAO,CAAC,EAAE,OAAO,GAAG;IACnB,oEAAoE;IACpE,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB,GACC,cAAc,CAAC,CAAC,CAAC,CAuJnB"}

package/dist/esm/utils/request.js

@@ -1,5 +1,14 @@
 import { makeRequestOptions } from "../lib/makeRequestOptions.js";
 import { getLines, getMessages } from "../vendor/fetch-event-source/parse.js";
+import { InferenceClientProviderApiError } from "../errors.js";
+function requestArgsToJson(args) {
+    // Convert the entire args object to a JSON-serializable format
+    const argsWithData = args;
+    return JSON.parse(JSON.stringify({
+        ...argsWithData,
+        data: argsWithData.data ? "[Blob or ArrayBuffer]" : null,
+    }));
+}
 /**
  * Primitive to make custom calls to the inference provider
  */
@@ -15,17 +24,37 @@ export async function innerRequest(args, providerHelper, options) {
         if (["application/json", "application/problem+json"].some((ct) => contentType?.startsWith(ct))) {
             const output = await response.json();
             if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-                throw new Error(`Server ${args.model} does not seem to support chat completion. Error: ${JSON.stringify(output.error)}`);
+                throw new InferenceClientProviderApiError(`Provider ${args.provider} does not seem to support chat completion for model ${args.model} . Error: ${JSON.stringify(output.error)}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
-            if (output.error || output.detail) {
-                throw new Error(JSON.stringify(output.error ?? output.detail));
+            if (typeof output.error === "string" || typeof output.detail === "string") {
+                throw new InferenceClientProviderApiError(`Failed to perform inference: ${output.error ?? output.detail}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
             else {
-                throw new Error(output);
+                throw new InferenceClientProviderApiError(`Failed to perform inference: an HTTP error occurred when requesting the provider.`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
         }
         const message = contentType?.startsWith("text/plain;") ? await response.text() : undefined;
-        throw new Error(message ?? "An error occurred while fetching the blob");
+        throw new InferenceClientProviderApiError(`Failed to perform inference: ${message ?? "an HTTP error occurred when requesting the provider"}`, {
+            url,
+            method: info.method ?? "GET",
+            headers: info.headers,
+            body: requestArgsToJson(args),
+        }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: message ?? "" });
     }
     if (response.headers.get("Content-Type")?.startsWith("application/json")) {
         const data = (await response.json());
@@ -47,24 +76,55 @@ export async function* innerStreamingRequest(args, providerHelper, options) {
         if (response.headers.get("Content-Type")?.startsWith("application/json")) {
             const output = await response.json();
             if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-                throw new Error(`Server ${args.model} does not seem to support chat completion. Error: ${output.error}`);
+                throw new InferenceClientProviderApiError(`Provider ${args.provider} does not seem to support chat completion for model ${args.model} . Error: ${JSON.stringify(output.error)}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
             if (typeof output.error === "string") {
-                throw new Error(output.error);
+                throw new InferenceClientProviderApiError(`Failed to perform inference: ${output.error}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
             if (output.error && "message" in output.error && typeof output.error.message === "string") {
                 /// OpenAI errors
-                throw new Error(output.error.message);
+                throw new InferenceClientProviderApiError(`Failed to perform inference: ${output.error.message}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
             // Sambanova errors
             if (typeof output.message === "string") {
-                throw new Error(output.message);
+                throw new InferenceClientProviderApiError(`Failed to perform inference: ${output.message}`, {
+                    url,
+                    method: info.method ?? "GET",
+                    headers: info.headers,
+                    body: requestArgsToJson(args),
+                }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output });
             }
         }
-        throw new Error(`Server response contains error: ${response.status}`);
+        throw new InferenceClientProviderApiError(`Failed to perform inference: an HTTP error occurred when requesting the provider.`, {
+            url,
+            method: info.method ?? "GET",
+            headers: info.headers,
+            body: requestArgsToJson(args),
+        }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: "" });
     }
     if (!response.headers.get("content-type")?.startsWith("text/event-stream")) {
-        throw new Error(`Server does not support event stream content type, it returned ` + response.headers.get("content-type"));
+        throw new InferenceClientProviderApiError(`Failed to perform inference: server does not support event stream content type, it returned ` +
+            response.headers.get("content-type"), {
+            url,
+            method: info.method ?? "GET",
+            headers: info.headers,
+            body: requestArgsToJson(args),
+        }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: "" });
     }
     if (!response.body) {
         return;
@@ -98,7 +158,12 @@ export async function* innerStreamingRequest(args, providerHelper, options) {
                                 typeof data.error.message === "string"
                                 ? data.error.message
                                 : JSON.stringify(data.error);
-                        throw new Error(`Error forwarded from backend: ` + errorStr);
+                        throw new InferenceClientProviderApiError(`Failed to perform inference: an occurred while streaming the response: ${errorStr}`, {
+                            url,
+                            method: info.method ?? "GET",
+                            headers: info.headers,
+                            body: requestArgsToJson(args),
+                        }, { requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: data });
                     }
                     yield data;
                 }

package/dist/esm/vendor/type-fest/basic.d.ts

@@ -0,0 +1,33 @@
+/**
+Matches a JSON object.
+
+This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category JSON
+*/
+export type JsonObject = {
+    [Key in string]: JsonValue;
+} & {
+    [Key in string]?: JsonValue | undefined;
+};
+/**
+Matches a JSON array.
+
+@category JSON
+*/
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+/**
+Matches any valid JSON primitive value.
+
+@category JSON
+*/
+export type JsonPrimitive = string | number | boolean | null;
+/**
+Matches any valid JSON value.
+
+@see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
+
+@category JSON
+*/
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+//# sourceMappingURL=basic.d.ts.map

package/dist/esm/vendor/type-fest/basic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basic.d.ts","sourceRoot":"","sources":["../../../../src/vendor/type-fest/basic.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AACF,MAAM,MAAM,UAAU,GAAG;KAAG,GAAG,IAAI,MAAM,GAAG,SAAS;CAAE,GAAG;KAAG,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS;CAAE,CAAC;AAEtG;;;;EAIE;AACF,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,GAAG,SAAS,SAAS,EAAE,CAAC;AAE3D;;;;EAIE;AACF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D;;;;;;EAME;AACF,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC"}

package/dist/esm/vendor/type-fest/basic.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huggingface/inference",
-  "version": "3.14.0",
+  "version": "4.0.0",
   "license": "MIT",
   "author": "Hugging Face and Tim Mikeladze <tim.mikeladze@gmail.com>",
   "description": "Typescript client for the Hugging Face Inference Providers and Inference Endpoints",
@@ -40,7 +40,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@huggingface/tasks": "^0.19.8",
+    "@huggingface/tasks": "^0.19.11",
     "@huggingface/jinja": "^0.5.0"
   },
   "devDependencies": {

package/src/errors.ts

@@ -0,0 +1,82 @@
+import type { JsonObject } from "./vendor/type-fest/basic.js";
+
+/**
+ * Base class for all inference-related errors.
+ */
+export abstract class InferenceClientError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "InferenceClientError";
+	}
+}
+
+export class InferenceClientInputError extends InferenceClientError {
+	constructor(message: string) {
+		super(message);
+		this.name = "InputError";
+	}
+}
+
+interface HttpRequest {
+	url: string;
+	method: string;
+	headers?: Record<string, string>;
+	body?: JsonObject;
+}
+
+interface HttpResponse {
+	requestId: string;
+	status: number;
+	body: JsonObject | string;
+}
+
+abstract class InferenceClientHttpRequestError extends InferenceClientError {
+	httpRequest: HttpRequest;
+	httpResponse: HttpResponse;
+	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
+		super(message);
+		this.httpRequest = {
+			...httpRequest,
+			...(httpRequest.headers
+				? {
+						headers: {
+							...httpRequest.headers,
+							...("Authorization" in httpRequest.headers ? { Authorization: `Bearer [redacted]` } : undefined),
+							/// redact authentication in the request headers
+						},
+				  }
+				: undefined),
+		};
+		this.httpResponse = httpResponse;
+	}
+}
+
+/**
+ * Thrown when the HTTP request to the provider fails, e.g. due to API issues or server errors.
+ */
+export class InferenceClientProviderApiError extends InferenceClientHttpRequestError {
+	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
+		super(message, httpRequest, httpResponse);
+		this.name = "ProviderApiError";
+	}
+}
+
+/**
+ * Thrown when the HTTP request to the hub fails, e.g. due to API issues or server errors.
+ */
+export class InferenceClientHubApiError extends InferenceClientHttpRequestError {
+	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
+		super(message, httpRequest, httpResponse);
+		this.name = "HubApiError";
+	}
+}
+
+/**
+ * Thrown when the inference output returned by the provider is invalid / does not match the expectations
+ */
+export class InferenceClientProviderOutputError extends InferenceClientError {
+	constructor(message: string) {
+		super(message);
+		this.name = "ProviderOutputError";
+	}
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 export { InferenceClient, InferenceClientEndpoint, HfInference } from "./InferenceClient.js";
-export { InferenceOutputError } from "./lib/InferenceOutputError.js";
+export * from "./errors.js";
 export * from "./types.js";
 export * from "./tasks/index.js";
 import * as snippets from "./snippets/index.js";

package/src/lib/getInferenceProviderMapping.ts

@@ -4,6 +4,7 @@ import { HARDCODED_MODEL_INFERENCE_MAPPING } from "../providers/consts.js";
 import { EQUIVALENT_SENTENCE_TRANSFORMERS_TASKS } from "../providers/hf-inference.js";
 import type { InferenceProvider, InferenceProviderOrPolicy, ModelId } from "../types.js";
 import { typedInclude } from "../utils/typedInclude.js";
+import { InferenceClientHubApiError, InferenceClientInputError } from "../errors.js";
 
 export const inferenceProviderMappingCache = new Map<ModelId, InferenceProviderMapping>();
 
@@ -32,27 +33,46 @@ export async function fetchInferenceProviderMappingForModel(
 		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 		inferenceProviderMapping = inferenceProviderMappingCache.get(modelId)!;
 	} else {
-		const resp = await (options?.fetch ?? fetch)(
-			`${HF_HUB_URL}/api/models/${modelId}?expand[]=inferenceProviderMapping`,
-			{
-				headers: accessToken?.startsWith("hf_") ? { Authorization: `Bearer ${accessToken}` } : {},
+		const url = `${HF_HUB_URL}/api/models/${modelId}?expand[]=inferenceProviderMapping`;
+		const resp = await (options?.fetch ?? fetch)(url, {
+			headers: accessToken?.startsWith("hf_") ? { Authorization: `Bearer ${accessToken}` } : {},
+		});
+		if (!resp.ok) {
+			if (resp.headers.get("Content-Type")?.startsWith("application/json")) {
+				const error = await resp.json();
+				if ("error" in error && typeof error.error === "string") {
+					throw new InferenceClientHubApiError(
+						`Failed to fetch inference provider mapping for model ${modelId}: ${error.error}`,
+						{ url, method: "GET" },
+						{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: error }
+					);
+				}
+			} else {
+				throw new InferenceClientHubApiError(
+					`Failed to fetch inference provider mapping for model ${modelId}`,
+					{ url, method: "GET" },
+					{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
+				);
 			}
-		);
-		if (resp.status === 404) {
-			throw new Error(`Model ${modelId} does not exist`);
 		}
-		inferenceProviderMapping = await resp
-			.json()
-			.then((json) => json.inferenceProviderMapping)
-			.catch(() => null);
-
-		if (inferenceProviderMapping) {
-			inferenceProviderMappingCache.set(modelId, inferenceProviderMapping);
+		let payload: { inferenceProviderMapping?: InferenceProviderMapping } | null = null;
+		try {
+			payload = await resp.json();
+		} catch {
+			throw new InferenceClientHubApiError(
+				`Failed to fetch inference provider mapping for model ${modelId}: malformed API response, invalid JSON`,
+				{ url, method: "GET" },
+				{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
+			);
 		}
-	}
-
-	if (!inferenceProviderMapping) {
-		throw new Error(`We have not been able to find inference provider information for model ${modelId}.`);
+		if (!payload?.inferenceProviderMapping) {
+			throw new InferenceClientHubApiError(
+				`We have not been able to find inference provider information for model ${modelId}.`,
+				{ url, method: "GET" },
+				{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
+			);
+		}
+		inferenceProviderMapping = payload.inferenceProviderMapping;
 	}
 	return inferenceProviderMapping;
 }
@@ -83,7 +103,7 @@ export async function getInferenceProviderMapping(
 				? EQUIVALENT_SENTENCE_TRANSFORMERS_TASKS
 				: [params.task];
 		if (!typedInclude(equivalentTasks, providerMapping.task)) {
-			throw new Error(
+			throw new InferenceClientInputError(
 				`Model ${params.modelId} is not supported for task ${params.task} and provider ${params.provider}. Supported task: ${providerMapping.task}.`
 			);
 		}
@@ -104,7 +124,7 @@ export async function resolveProvider(
 ): Promise<InferenceProvider> {
 	if (endpointUrl) {
 		if (provider) {
-			throw new Error("Specifying both endpointUrl and provider is not supported.");
+			throw new InferenceClientInputError("Specifying both endpointUrl and provider is not supported.");
 		}
 		/// Defaulting to hf-inference helpers / API
 		return "hf-inference";
@@ -117,13 +137,13 @@ export async function resolveProvider(
 	}
 	if (provider === "auto") {
 		if (!modelId) {
-			throw new Error("Specifying a model is required when provider is 'auto'");
+			throw new InferenceClientInputError("Specifying a model is required when provider is 'auto'");
 		}
 		const inferenceProviderMapping = await fetchInferenceProviderMappingForModel(modelId);
 		provider = Object.keys(inferenceProviderMapping)[0] as InferenceProvider | undefined;
 	}
 	if (!provider) {
-		throw new Error(`No Inference Provider available for model ${modelId}.`);
+		throw new InferenceClientInputError(`No Inference Provider available for model ${modelId}.`);
 	}
 	return provider;
 }

package/src/lib/getProviderHelper.ts

@@ -48,6 +48,7 @@ import * as Replicate from "../providers/replicate.js";
 import * as Sambanova from "../providers/sambanova.js";
 import * as Together from "../providers/together.js";
 import type { InferenceProvider, InferenceProviderOrPolicy, InferenceTask } from "../types.js";
+import { InferenceClientInputError } from "../errors.js";
 
 export const PROVIDERS: Record<InferenceProvider, Partial<Record<InferenceTask, TaskProviderHelper>>> = {
 	"black-forest-labs": {
@@ -120,6 +121,7 @@ export const PROVIDERS: Record<InferenceProvider, Partial<Record<InferenceTask,
 	novita: {
 		conversational: new Novita.NovitaConversationalTask(),
 		"text-generation": new Novita.NovitaTextGenerationTask(),
+		"text-to-video": new Novita.NovitaTextToVideoTask(),
 	},
 	nscale: {
 		"text-to-image": new Nscale.NscaleTextToImageTask(),
@@ -280,14 +282,18 @@ export function getProviderHelper(
 		return new HFInference.HFInferenceTask();
 	}
 	if (!task) {
-		throw new Error("you need to provide a task name when using an external provider, e.g. 'text-to-image'");
+		throw new InferenceClientInputError(
+			"you need to provide a task name when using an external provider, e.g. 'text-to-image'"
+		);
 	}
 	if (!(provider in PROVIDERS)) {
-		throw new Error(`Provider '${provider}' not supported. Available providers: ${Object.keys(PROVIDERS)}`);
+		throw new InferenceClientInputError(
+			`Provider '${provider}' not supported. Available providers: ${Object.keys(PROVIDERS)}`
+		);
 	}
 	const providerTasks = PROVIDERS[provider];
 	if (!providerTasks || !(task in providerTasks)) {
-		throw new Error(
+		throw new InferenceClientInputError(
 			`Task '${task}' not supported for provider '${provider}'. Available tasks: ${Object.keys(providerTasks ?? {})}`
 		);
 	}

package/src/lib/makeRequestOptions.ts

@@ -5,6 +5,7 @@ import type { InferenceProviderModelMapping } from "./getInferenceProviderMappin
 import { getInferenceProviderMapping } from "./getInferenceProviderMapping.js";
 import type { getProviderHelper } from "./getProviderHelper.js";
 import { isUrl } from "./isUrl.js";
+import { InferenceClientHubApiError, InferenceClientInputError } from "../errors.js";
 
 /**
  * Lazy-loaded from huggingface.co/api/tasks when needed
@@ -33,10 +34,10 @@ export async function makeRequestOptions(
 
 	// Validate inputs
 	if (args.endpointUrl && provider !== "hf-inference") {
-		throw new Error(`Cannot use endpointUrl with a third-party provider.`);
+		throw new InferenceClientInputError(`Cannot use endpointUrl with a third-party provider.`);
 	}
 	if (maybeModel && isUrl(maybeModel)) {
-		throw new Error(`Model URLs are no longer supported. Use endpointUrl instead.`);
+		throw new InferenceClientInputError(`Model URLs are no longer supported. Use endpointUrl instead.`);
 	}
 
 	if (args.endpointUrl) {
@@ -51,14 +52,14 @@ export async function makeRequestOptions(
 	}
 
 	if (!maybeModel && !task) {
-		throw new Error("No model provided, and no task has been specified.");
+		throw new InferenceClientInputError("No model provided, and no task has been specified.");
 	}
 
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const hfModel = maybeModel ?? (await loadDefaultModel(task!));
 
 	if (providerHelper.clientSideRoutingOnly && !maybeModel) {
-		throw new Error(`Provider ${provider} requires a model ID to be passed directly.`);
+		throw new InferenceClientInputError(`Provider ${provider} requires a model ID to be passed directly.`);
 	}
 
 	const inferenceProviderMapping = providerHelper.clientSideRoutingOnly
@@ -82,7 +83,9 @@ export async function makeRequestOptions(
 				{ fetch: options?.fetch }
 		  );
 	if (!inferenceProviderMapping) {
-		throw new Error(`We have not been able to find inference provider information for model ${hfModel}.`);
+		throw new InferenceClientInputError(
+			`We have not been able to find inference provider information for model ${hfModel}.`
+		);
 	}
 
 	// Use the sync version with the resolved model
@@ -122,9 +125,8 @@ export function makeRequestOptionsFromResolvedModel(
 		if (providerHelper.clientSideRoutingOnly) {
 			// Closed-source providers require an accessToken (cannot be routed).
 			if (accessToken && accessToken.startsWith("hf_")) {
-				throw new Error(`Provider ${provider} is closed-source and does not support HF tokens.`);
+				throw new InferenceClientInputError(`Provider ${provider} is closed-source and does not support HF tokens.`);
 			}
-			return "provider-key";
 		}
 		if (accessToken) {
 			return accessToken.startsWith("hf_") ? "hf-token" : "provider-key";
@@ -197,23 +199,30 @@ async function loadDefaultModel(task: InferenceTask): Promise<string> {
 	}
 	const taskInfo = tasks[task];
 	if ((taskInfo?.models.length ?? 0) <= 0) {
-		throw new Error(`No default model defined for task ${task}, please define the model explicitly.`);
+		throw new InferenceClientInputError(
+			`No default model defined for task ${task}, please define the model explicitly.`
+		);
 	}
 	return taskInfo.models[0].id;
 }
 
 async function loadTaskInfo(): Promise<Record<string, { models: { id: string }[] }>> {
-	const res = await fetch(`${HF_HUB_URL}/api/tasks`);
+	const url = `${HF_HUB_URL}/api/tasks`;
+	const res = await fetch(url);
 
 	if (!res.ok) {
-		throw new Error("Failed to load tasks definitions from Hugging Face Hub.");
+		throw new InferenceClientHubApiError(
+			"Failed to load tasks definitions from Hugging Face Hub.",
+			{ url, method: "GET" },
+			{ requestId: res.headers.get("x-request-id") ?? "", status: res.status, body: await res.text() }
+		);
 	}
 	return await res.json();
 }
 
 function removeProviderPrefix(model: string, provider: string): string {
 	if (!model.startsWith(`${provider}/`)) {
-		throw new Error(`Models from ${provider} must be prefixed by "${provider}/". Got "${model}".`);
+		throw new InferenceClientInputError(`Models from ${provider} must be prefixed by "${provider}/". Got "${model}".`);
 	}
 	return model.slice(provider.length + 1);
 }

package/src/package.ts

@@ -1,3 +1,3 @@
 // Generated file from package.json. Issues importing JSON directly when publishing on commonjs/ESM - see https://github.com/microsoft/TypeScript/issues/51783
-export const PACKAGE_VERSION = "3.14.0";
+export const PACKAGE_VERSION = "4.0.0";
 export const PACKAGE_NAME = "@huggingface/inference";

package/src/providers/black-forest-labs.ts

@@ -14,7 +14,11 @@
  *
  * Thanks!
  */
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
+import {
+	InferenceClientInputError,
+	InferenceClientProviderApiError,
+	InferenceClientProviderOutputError,
+} from "../errors.js";
 import type { BodyParams, HeaderParams, UrlParams } from "../types.js";
 import { delay } from "../utils/delay.js";
 import { omit } from "../utils/omit.js";
@@ -52,7 +56,7 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 
 	makeRoute(params: UrlParams): string {
 		if (!params) {
-			throw new Error("Params are required");
+			throw new InferenceClientInputError("Params are required");
 		}
 		return `/v1/${params.model}`;
 	}
@@ -70,7 +74,11 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 			urlObj.searchParams.set("attempt", step.toString(10));
 			const resp = await fetch(urlObj, { headers: { "Content-Type": "application/json" } });
 			if (!resp.ok) {
-				throw new InferenceOutputError("Failed to fetch result from black forest labs API");
+				throw new InferenceClientProviderApiError(
+					"Failed to fetch result from black forest labs API",
+					{ url: urlObj.toString(), method: "GET", headers: { "Content-Type": "application/json" } },
+					{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
+				);
 			}
 			const payload = await resp.json();
 			if (
@@ -92,6 +100,8 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 				return await image.blob();
 			}
 		}
-		throw new InferenceOutputError("Failed to fetch result from black forest labs API");
+		throw new InferenceClientProviderOutputError(
+			`Timed out while waiting for the result from black forest labs API - aborting after 5 attempts`
+		);
 	}
 }