@huggingface/inference 3.0.0 → 3.1.0

package/README.md

@@ -42,15 +42,15 @@ const hf = new HfInference('your access token')
 
 Your access token should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the access token.
 
-### Requesting third-party inference providers
+### Third-party inference providers
 
-You can request inference from third-party providers with the inference client.
+You can send inference requests to third-party providers with the inference client.
 
 Currently, we support the following providers: [Fal.ai](https://fal.ai), [Replicate](https://replicate.com), [Together](https://together.xyz) and [Sambanova](https://sambanova.ai).
 
-To make request to a third-party provider, you have to pass the `provider` parameter to the inference function. Make sure your request is authenticated with an access token.
+To send requests to a third-party provider, you have to pass the `provider` parameter to the inference function. Make sure your request is authenticated with an access token.
 ```ts
-const accessToken = "hf_..."; // Either a HF access token, or an API key from the 3rd party provider (Replicate in this example)
+const accessToken = "hf_..."; // Either a HF access token, or an API key from the third-party provider (Replicate in this example)
 
 const client = new HfInference(accessToken);
 await client.textToImage({
@@ -63,14 +63,19 @@ await client.textToImage({
 When authenticated with a Hugging Face access token, the request is routed through https://huggingface.co.
 When authenticated with a third-party provider key, the request is made directly against that provider's inference API.
 
-Only a subset of models are supported when requesting 3rd party providers. You can check the list of supported models per pipeline tasks here:
+Only a subset of models are supported when requesting third-party providers. You can check the list of supported models per pipeline tasks here:
 - [Fal.ai supported models](./src/providers/fal-ai.ts)
 - [Replicate supported models](./src/providers/replicate.ts)
 - [Sambanova supported models](./src/providers/sambanova.ts)
 - [Together supported models](./src/providers/together.ts)
 - [HF Inference API (serverless)](https://huggingface.co/models?inference=warm&sort=trending)
 
-#### Tree-shaking
+❗**Important note:** To be compatible, the third-party API must adhere to the "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. Let us know if any help is needed or if we can make things easier for you!
+
+👋**Want to add another provider?** Get in touch if you'd like to add support for another Inference provider, and/or request it on https://huggingface.co/spaces/huggingface/HuggingDiscussions/discussions/49
+
+### Tree-shaking
 
 You can import the functions you need directly from the module instead of using the `HfInference` class.
 

package/dist/index.cjs

@@ -107,10 +107,22 @@ var FAL_AI_API_BASE_URL = "https://fal.run";
 var FAL_AI_SUPPORTED_MODEL_IDS = {
   "text-to-image": {
     "black-forest-labs/FLUX.1-schnell": "fal-ai/flux/schnell",
-    "black-forest-labs/FLUX.1-dev": "fal-ai/flux/dev"
+    "black-forest-labs/FLUX.1-dev": "fal-ai/flux/dev",
+    "playgroundai/playground-v2.5-1024px-aesthetic": "fal-ai/playground-v25",
+    "ByteDance/SDXL-Lightning": "fal-ai/lightning-models",
+    "PixArt-alpha/PixArt-Sigma-XL-2-1024-MS": "fal-ai/pixart-sigma",
+    "stabilityai/stable-diffusion-3-medium": "fal-ai/stable-diffusion-v3-medium",
+    "Warlord-K/Sana-1024": "fal-ai/sana",
+    "fal/AuraFlow-v0.2": "fal-ai/aura-flow",
+    "stabilityai/stable-diffusion-3.5-large": "fal-ai/stable-diffusion-v35-large",
+    "Kwai-Kolors/Kolors": "fal-ai/kolors"
   },
   "automatic-speech-recognition": {
     "openai/whisper-large-v3": "fal-ai/whisper"
+  },
+  "text-to-video": {
+    "genmo/mochi-1-preview": "fal-ai/mochi-v1",
+    "tencent/HunyuanVideo": "fal-ai/hunyuan-video"
   }
 };
 
@@ -120,10 +132,13 @@ var REPLICATE_SUPPORTED_MODEL_IDS = {
   "text-to-image": {
     "black-forest-labs/FLUX.1-schnell": "black-forest-labs/flux-schnell",
     "ByteDance/SDXL-Lightning": "bytedance/sdxl-lightning-4step:5599ed30703defd1d160a25a63321b4dec97101d98b4674bcc56e41f62f35637"
+  },
+  "text-to-speech": {
+    "OuteAI/OuteTTS-0.3-500M": "jbilcke/oute-tts:39a59319327b27327fa3095149c5a746e7f2aee18c75055c3368237a6503cd26"
+  },
+  "text-to-video": {
+    "genmo/mochi-1-preview": "genmoai/mochi-1:1944af04d098ef69bed7f9d335d102e652203f268ec4aaa2d836f6217217e460"
   }
-  // "text-to-speech": {
-  // 	"SWivid/F5-TTS": "x-lance/f5-tts:87faf6dd7a692dd82043f662e76369cab126a2cf1937e25a9d41e0b834fd230e"
-  // },
 };
 
 // src/providers/sambanova.ts
@@ -159,6 +174,8 @@ var TOGETHER_SUPPORTED_MODEL_IDS = {
   },
   conversational: {
     "databricks/dbrx-instruct": "databricks/dbrx-instruct",
+    "deepseek-ai/DeepSeek-R1": "deepseek-ai/DeepSeek-R1",
+    "deepseek-ai/DeepSeek-V3": "deepseek-ai/DeepSeek-V3",
     "deepseek-ai/deepseek-llm-67b-chat": "deepseek-ai/deepseek-llm-67b-chat",
     "google/gemma-2-9b-it": "google/gemma-2-9b-it",
     "google/gemma-2b-it": "google/gemma-2-27b-it",
@@ -204,7 +221,8 @@ function isUrl(modelOrUrl) {
 var HF_HUB_INFERENCE_PROXY_TEMPLATE = `${HF_HUB_URL}/api/inference-proxy/{{PROVIDER}}`;
 var tasks = null;
 async function makeRequestOptions(args, options) {
-  const { accessToken, endpointUrl, provider: maybeProvider, model: maybeModel, ...otherArgs } = args;
+  const { accessToken, endpointUrl, provider: maybeProvider, model: maybeModel, ...remainingArgs } = args;
+  let otherArgs = remainingArgs;
   const provider = maybeProvider ?? "hf-inference";
   const { forceTask, includeCredentials, taskHint, wait_for_model, use_cache, dont_load_model, chatCompletion: chatCompletion2 } = options ?? {};
   if (endpointUrl && provider !== "hf-inference") {
@@ -263,9 +281,9 @@ async function makeRequestOptions(args, options) {
   } else if (includeCredentials === true) {
     credentials = "include";
   }
-  if (provider === "replicate" && model.includes(":")) {
-    const version = model.split(":")[1];
-    otherArgs.version = version;
+  if (provider === "replicate") {
+    const version = model.includes(":") ? model.split(":")[1] : void 0;
+    otherArgs = { input: otherArgs, version };
   }
   const info = {
     headers,
@@ -585,9 +603,42 @@ var InferenceOutputError = class extends TypeError {
   }
 };
 
+// src/utils/pick.ts
+function pick(o, props) {
+  return Object.assign(
+    {},
+    ...props.map((prop) => {
+      if (o[prop] !== void 0) {
+        return { [prop]: o[prop] };
+      }
+    })
+  );
+}
+
+// src/utils/typedInclude.ts
+function typedInclude(arr, v) {
+  return arr.includes(v);
+}
+
+// src/utils/omit.ts
+function omit(o, props) {
+  const propsArr = Array.isArray(props) ? props : [props];
+  const letsKeep = Object.keys(o).filter((prop) => !typedInclude(propsArr, prop));
+  return pick(o, letsKeep);
+}
+
+// src/tasks/audio/utils.ts
+function preparePayload(args) {
+  return "data" in args ? args : {
+    ...omit(args, "inputs"),
+    data: args.inputs
+  };
+}
+
 // src/tasks/audio/audioClassification.ts
 async function audioClassification(args, options) {
-  const res = await request(args, {
+  const payload = preparePayload(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "audio-classification"
   });
@@ -613,15 +664,8 @@ function base64FromBytes(arr) {
 
 // src/tasks/audio/automaticSpeechRecognition.ts
 async function automaticSpeechRecognition(args, options) {
-  if (args.provider === "fal-ai") {
-    const contentType = args.data instanceof Blob ? args.data.type : "audio/mpeg";
-    const base64audio = base64FromBytes(
-      new Uint8Array(args.data instanceof ArrayBuffer ? args.data : await args.data.arrayBuffer())
-    );
-    args.audio_url = `data:${contentType};base64,${base64audio}`;
-    delete args.data;
-  }
-  const res = await request(args, {
+  const payload = await buildPayload(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "automatic-speech-recognition"
   });
@@ -631,6 +675,32 @@ async function automaticSpeechRecognition(args, options) {
   }
   return res;
 }
+var FAL_AI_SUPPORTED_BLOB_TYPES = ["audio/mpeg", "audio/mp4", "audio/wav", "audio/x-wav"];
+async function buildPayload(args) {
+  if (args.provider === "fal-ai") {
+    const blob = "data" in args && args.data instanceof Blob ? args.data : "inputs" in args ? args.inputs : void 0;
+    const contentType = blob?.type;
+    if (!contentType) {
+      throw new Error(
+        `Unable to determine the input's content-type. Make sure your are passing a Blob when using provider fal-ai.`
+      );
+    }
+    if (!FAL_AI_SUPPORTED_BLOB_TYPES.includes(contentType)) {
+      throw new Error(
+        `Provider fal-ai does not support blob type ${contentType} - supported content types are: ${FAL_AI_SUPPORTED_BLOB_TYPES.join(
+          ", "
+        )}`
+      );
+    }
+    const base64audio = base64FromBytes(new Uint8Array(await blob.arrayBuffer()));
+    return {
+      ..."data" in args ? omit(args, "data") : omit(args, "inputs"),
+      audio_url: `data:${contentType};base64,${base64audio}`
+    };
+  } else {
+    return preparePayload(args);
+  }
+}
 
 // src/tasks/audio/textToSpeech.ts
 async function textToSpeech(args, options) {
@@ -638,31 +708,55 @@ async function textToSpeech(args, options) {
     ...options,
     taskHint: "text-to-speech"
   });
-  const isValidOutput = res && res instanceof Blob;
-  if (!isValidOutput) {
-    throw new InferenceOutputError("Expected Blob");
+  if (res instanceof Blob) {
+    return res;
   }
-  return res;
+  if (res && typeof res === "object") {
+    if ("output" in res) {
+      if (typeof res.output === "string") {
+        const urlResponse = await fetch(res.output);
+        const blob = await urlResponse.blob();
+        return blob;
+      } else if (Array.isArray(res.output)) {
+        const urlResponse = await fetch(res.output[0]);
+        const blob = await urlResponse.blob();
+        return blob;
+      }
+    }
+  }
+  throw new InferenceOutputError("Expected Blob or object with output");
 }
 
 // src/tasks/audio/audioToAudio.ts
 async function audioToAudio(args, options) {
-  const res = await request(args, {
+  const payload = preparePayload(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "audio-to-audio"
   });
-  const isValidOutput = Array.isArray(res) && res.every(
-    (x) => typeof x.label === "string" && typeof x.blob === "string" && typeof x["content-type"] === "string"
-  );
-  if (!isValidOutput) {
-    throw new InferenceOutputError("Expected Array<{label: string, blob: string, content-type: string}>");
+  return validateOutput(res);
+}
+function validateOutput(output) {
+  if (!Array.isArray(output)) {
+    throw new InferenceOutputError("Expected Array");
   }
-  return res;
+  if (!output.every((elem) => {
+    return typeof elem === "object" && elem && "label" in elem && typeof elem.label === "string" && "content-type" in elem && typeof elem["content-type"] === "string" && "blob" in elem && typeof elem.blob === "string";
+  })) {
+    throw new InferenceOutputError("Expected Array<{label: string, audio: Blob}>");
+  }
+  return output;
+}
+
+// src/tasks/cv/utils.ts
+function preparePayload2(args) {
+  return "data" in args ? args : { ...omit(args, "inputs"), data: args.inputs };
 }
 
 // src/tasks/cv/imageClassification.ts
 async function imageClassification(args, options) {
-  const res = await request(args, {
+  const payload = preparePayload2(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "image-classification"
   });
@@ -675,7 +769,8 @@ async function imageClassification(args, options) {
 
 // src/tasks/cv/imageSegmentation.ts
 async function imageSegmentation(args, options) {
-  const res = await request(args, {
+  const payload = preparePayload2(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "image-segmentation"
   });
@@ -688,7 +783,8 @@ async function imageSegmentation(args, options) {
 
 // src/tasks/cv/imageToText.ts
 async function imageToText(args, options) {
-  const res = (await request(args, {
+  const payload = preparePayload2(args);
+  const res = (await request(payload, {
     ...options,
     taskHint: "image-to-text"
   }))?.[0];
@@ -700,7 +796,8 @@ async function imageToText(args, options) {
 
 // src/tasks/cv/objectDetection.ts
 async function objectDetection(args, options) {
-  const res = await request(args, {
+  const payload = preparePayload2(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "object-detection"
   });
@@ -717,15 +814,13 @@ async function objectDetection(args, options) {
 
 // src/tasks/cv/textToImage.ts
 async function textToImage(args, options) {
-  if (args.provider === "together" || args.provider === "fal-ai") {
-    args.prompt = args.inputs;
-    args.inputs = "";
-    args.response_format = "base64";
-  } else if (args.provider === "replicate") {
-    args.input = { prompt: args.inputs };
-    delete args.inputs;
-  }
-  const res = await request(args, {
+  const payload = args.provider === "together" || args.provider === "fal-ai" || args.provider === "replicate" ? {
+    ...omit(args, ["inputs", "parameters"]),
+    ...args.parameters,
+    ...args.provider !== "replicate" ? { response_format: "base64" } : void 0,
+    prompt: args.inputs
+  } : args;
+  const res = await request(payload, {
     ...options,
     taskHint: "text-to-image"
   });
@@ -782,18 +877,30 @@ async function imageToImage(args, options) {
 }
 
 // src/tasks/cv/zeroShotImageClassification.ts
-async function zeroShotImageClassification(args, options) {
-  const reqArgs = {
-    ...args,
-    inputs: {
-      image: base64FromBytes(
-        new Uint8Array(
-          args.inputs.image instanceof ArrayBuffer ? args.inputs.image : await args.inputs.image.arrayBuffer()
+async function preparePayload3(args) {
+  if (args.inputs instanceof Blob) {
+    return {
+      ...args,
+      inputs: {
+        image: base64FromBytes(new Uint8Array(await args.inputs.arrayBuffer()))
+      }
+    };
+  } else {
+    return {
+      ...args,
+      inputs: {
+        image: base64FromBytes(
+          new Uint8Array(
+            args.inputs.image instanceof ArrayBuffer ? args.inputs.image : await args.inputs.image.arrayBuffer()
+          )
         )
-      )
-    }
-  };
-  const res = await request(reqArgs, {
+      }
+    };
+  }
+}
+async function zeroShotImageClassification(args, options) {
+  const payload = await preparePayload3(args);
+  const res = await request(payload, {
     ...options,
     taskHint: "zero-shot-image-classification"
   });
@@ -882,17 +989,19 @@ async function questionAnswering(args, options) {
     ...options,
     taskHint: "question-answering"
   });
-  const isValidOutput = typeof res === "object" && !!res && typeof res.answer === "string" && typeof res.end === "number" && typeof res.score === "number" && typeof res.start === "number";
+  const isValidOutput = Array.isArray(res) ? res.every(
+    (elem) => typeof elem === "object" && !!elem && typeof elem.answer === "string" && typeof elem.end === "number" && typeof elem.score === "number" && typeof elem.start === "number"
+  ) : typeof res === "object" && !!res && typeof res.answer === "string" && typeof res.end === "number" && typeof res.score === "number" && typeof res.start === "number";
   if (!isValidOutput) {
-    throw new InferenceOutputError("Expected {answer: string, end: number, score: number, start: number}");
+    throw new InferenceOutputError("Expected Array<{answer: string, end: number, score: number, start: number}>");
   }
-  return res;
+  return Array.isArray(res) ? res[0] : res;
 }
 
 // src/tasks/nlp/sentenceSimilarity.ts
 async function sentenceSimilarity(args, options) {
   const defaultTask = args.model ? await getDefaultTask(args.model, args.accessToken, options) : void 0;
-  const res = await request(args, {
+  const res = await request(prepareInput(args), {
     ...options,
     taskHint: "sentence-similarity",
     ...defaultTask === "feature-extraction" && { forceTask: "sentence-similarity" }
@@ -903,6 +1012,13 @@ async function sentenceSimilarity(args, options) {
   }
   return res;
 }
+function prepareInput(args) {
+  return {
+    ...omit(args, ["inputs", "parameters"]),
+    inputs: { ...omit(args.inputs, "sourceSentence") },
+    parameters: { source_sentence: args.inputs.sourceSentence, ...args.parameters }
+  };
+}
 
 // src/tasks/nlp/summarization.ts
 async function summarization(args, options) {
@@ -923,13 +1039,18 @@ async function tableQuestionAnswering(args, options) {
     ...options,
     taskHint: "table-question-answering"
   });
-  const isValidOutput = typeof res?.aggregator === "string" && typeof res.answer === "string" && Array.isArray(res.cells) && res.cells.every((x) => typeof x === "string") && Array.isArray(res.coordinates) && res.coordinates.every((coord) => Array.isArray(coord) && coord.every((x) => typeof x === "number"));
+  const isValidOutput = Array.isArray(res) ? res.every((elem) => validate(elem)) : validate(res);
   if (!isValidOutput) {
     throw new InferenceOutputError(
       "Expected {aggregator: string, answer: string, cells: string[], coordinates: number[][]}"
     );
   }
-  return res;
+  return Array.isArray(res) ? res[0] : res;
+}
+function validate(elem) {
+  return typeof elem === "object" && !!elem && "aggregator" in elem && typeof elem.aggregator === "string" && "answer" in elem && typeof elem.answer === "string" && "cells" in elem && Array.isArray(elem.cells) && elem.cells.every((x) => typeof x === "string") && "coordinates" in elem && Array.isArray(elem.coordinates) && elem.coordinates.every(
+    (coord) => Array.isArray(coord) && coord.every((x) => typeof x === "number")
+  );
 }
 
 // src/tasks/nlp/textClassification.ts
@@ -1072,11 +1193,7 @@ async function documentQuestionAnswering(args, options) {
     inputs: {
       question: args.inputs.question,
       // convert Blob or ArrayBuffer to base64
-      image: base64FromBytes(
-        new Uint8Array(
-          args.inputs.image instanceof ArrayBuffer ? args.inputs.image : await args.inputs.image.arrayBuffer()
-        )
-      )
+      image: base64FromBytes(new Uint8Array(await args.inputs.image.arrayBuffer()))
     }
   };
   const res = toArray(
@@ -1084,12 +1201,14 @@ async function documentQuestionAnswering(args, options) {
       ...options,
       taskHint: "document-question-answering"
     })
-  )?.[0];
-  const isValidOutput = typeof res?.answer === "string" && (typeof res.end === "number" || typeof res.end === "undefined") && (typeof res.score === "number" || typeof res.score === "undefined") && (typeof res.start === "number" || typeof res.start === "undefined");
+  );
+  const isValidOutput = Array.isArray(res) && res.every(
+    (elem) => typeof elem === "object" && !!elem && typeof elem?.answer === "string" && (typeof elem.end === "number" || typeof elem.end === "undefined") && (typeof elem.score === "number" || typeof elem.score === "undefined") && (typeof elem.start === "number" || typeof elem.start === "undefined")
+  );
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{answer: string, end?: number, score?: number, start?: number}>");
   }
-  return res;
+  return res[0];
 }
 
 // src/tasks/multimodal/visualQuestionAnswering.ts
@@ -1099,22 +1218,20 @@ async function visualQuestionAnswering(args, options) {
     inputs: {
       question: args.inputs.question,
       // convert Blob or ArrayBuffer to base64
-      image: base64FromBytes(
-        new Uint8Array(
-          args.inputs.image instanceof ArrayBuffer ? args.inputs.image : await args.inputs.image.arrayBuffer()
-        )
-      )
+      image: base64FromBytes(new Uint8Array(await args.inputs.image.arrayBuffer()))
     }
   };
-  const res = (await request(reqArgs, {
+  const res = await request(reqArgs, {
     ...options,
     taskHint: "visual-question-answering"
-  }))?.[0];
-  const isValidOutput = typeof res?.answer === "string" && typeof res.score === "number";
+  });
+  const isValidOutput = Array.isArray(res) && res.every(
+    (elem) => typeof elem === "object" && !!elem && typeof elem?.answer === "string" && typeof elem.score === "number"
+  );
   if (!isValidOutput) {
     throw new InferenceOutputError("Expected Array<{answer: string, score: number}>");
   }
-  return res;
+  return res[0];
 }
 
 // src/tasks/tabular/tabularRegression.ts