@huggingface/inference 1.4.2 → 1.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 TimMikeladze
+Copyright (c) 2022 Tim Mikeladze
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -19,9 +19,9 @@ pnpm add @huggingface/inference
 ### Basic examples
 
 ```typescript
-import HuggingFace from 'huggingface'
+import { HfInference } from '@huggingface/inference'
 
-const hf = new HuggingFace('your api key')
+const hf = new HfInference('your api key')
 
 // Natural Language
 
@@ -137,6 +137,12 @@ await hf.imageSegmentation({
   data: readFileSync('test/cats.png'),
   model: 'facebook/detr-resnet-50-panoptic'
 })
+
+await hf.textToImage({
+  inputs: 'award winning high resolution photo of a giant tortoise/((ladybird)) hybrid, [trending on artstation]',
+  negative_prompt: 'blurry',
+  model: 'stabilityai/stable-diffusion-2',
+})
 ```
 
 ## Supported APIs
@@ -167,6 +173,7 @@ await hf.imageSegmentation({
 - [x] Image classification
 - [x] Object detection
 - [x] Image segmentation
+- [x] Text to image
 
 ## Running tests
 
@@ -177,7 +184,7 @@ HF_ACCESS_TOKEN="your access token" npm run test
 ## Options
 
 ```typescript
-export declare class HuggingFace {
+export declare class HfInference {
   private readonly apiKey
   private readonly defaultOptions
   constructor(apiKey: string, defaultOptions?: Options)
@@ -296,6 +303,12 @@ export declare class HuggingFace {
     args: ImageSegmentationArgs,
     options?: Options
   ): Promise<ImageSegmentationReturn>
+
+  /**
+   * This task reads some text input and outputs an image.
+   * Recommended model: stabilityai/stable-diffusion-2
+   */
+  textToImage(args: TextToImageArgs, options?: Options): Promise<TextToImageReturn>;
   request(
     args: Args & {
       data?: any
@@ -752,4 +765,15 @@ export declare type AudioClassificationReturnValue = {
   score: number
 }
 export declare type AudioClassificationReturn = AudioClassificationReturnValue[]
+type TextToImageArgs = Args & {
+  /**
+   * The text to generate an image from
+   */
+  inputs: string
+  /**
+   * An optional negative prompt for the image generation
+   */
+  negative_prompt?: string
+};
+type TextToImageReturn = ArrayBuffer
 ```

package/dist/index.d.ts

@@ -442,7 +442,18 @@ type AudioClassificationReturnValue = {
     score: number;
 };
 type AudioClassificationReturn = AudioClassificationReturnValue[];
-declare class HuggingFace {
+type TextToImageArgs = Args & {
+    /**
+     * The text to generate an image from
+     */
+    inputs: string;
+    /**
+     * An optional negative prompt for the image generation
+     */
+    negative_prompt?: string;
+};
+type TextToImageReturn = ArrayBuffer;
+declare class HfInference {
     private readonly apiKey;
     private readonly defaultOptions;
     constructor(apiKey: string, defaultOptions?: Options);
@@ -516,12 +527,18 @@ declare class HuggingFace {
      * Recommended model: facebook/detr-resnet-50-panoptic
      */
     imageSegmentation(args: ImageSegmentationArgs, options?: Options): Promise<ImageSegmentationReturn>;
+    /**
+     * This task reads some text input and outputs an image.
+     * Recommended model: stabilityai/stable-diffusion-2
+     */
+    textToImage(args: TextToImageArgs, options?: Options): Promise<TextToImageReturn>;
     request(args: Args & {
         data?: any;
     }, options?: Options & {
         binary?: boolean;
+        blob?: boolean;
     }): Promise<any>;
     private static toArray;
 }
 
-export { Args, AudioClassificationArgs, AudioClassificationReturn, AudioClassificationReturnValue, AutomaticSpeechRecognitionArgs, AutomaticSpeechRecognitionReturn, ConversationalArgs, ConversationalReturn, FeatureExtractionArgs, FeatureExtractionReturn, FillMaskArgs, FillMaskReturn, HuggingFace, ImageClassificationArgs, ImageClassificationReturn, ImageClassificationReturnValue, ImageSegmentationArgs, ImageSegmentationReturn, ImageSegmentationReturnValue, ObjectDetectionArgs, ObjectDetectionReturn, ObjectDetectionReturnValue, Options, QuestionAnswerArgs, QuestionAnswerReturn, SummarizationArgs, SummarizationReturn, TableQuestionAnswerArgs, TableQuestionAnswerReturn, TextClassificationArgs, TextClassificationReturn, TextGenerationArgs, TextGenerationReturn, TokenClassificationArgs, TokenClassificationReturn, TokenClassificationReturnValue, TranslationArgs, TranslationReturn, ZeroShotClassificationArgs, ZeroShotClassificationReturn, ZeroShotClassificationReturnValue, HuggingFace as default };
+export { Args, AudioClassificationArgs, AudioClassificationReturn, AudioClassificationReturnValue, AutomaticSpeechRecognitionArgs, AutomaticSpeechRecognitionReturn, ConversationalArgs, ConversationalReturn, FeatureExtractionArgs, FeatureExtractionReturn, FillMaskArgs, FillMaskReturn, HfInference, ImageClassificationArgs, ImageClassificationReturn, ImageClassificationReturnValue, ImageSegmentationArgs, ImageSegmentationReturn, ImageSegmentationReturnValue, ObjectDetectionArgs, ObjectDetectionReturn, ObjectDetectionReturnValue, Options, QuestionAnswerArgs, QuestionAnswerReturn, SummarizationArgs, SummarizationReturn, TableQuestionAnswerArgs, TableQuestionAnswerReturn, TextClassificationArgs, TextClassificationReturn, TextGenerationArgs, TextGenerationReturn, TextToImageArgs, TextToImageReturn, TokenClassificationArgs, TokenClassificationReturn, TokenClassificationReturnValue, TranslationArgs, TranslationReturn, ZeroShotClassificationArgs, ZeroShotClassificationReturn, ZeroShotClassificationReturnValue };

package/dist/index.js

@@ -19,13 +19,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  HuggingFace: () => HuggingFace,
-  default: () => src_default
+  HfInference: () => HfInference
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/HuggingFace.ts
-var HuggingFace = class {
+// src/HfInference.ts
+var HfInference = class {
   apiKey;
   defaultOptions;
   constructor(apiKey, defaultOptions = {}) {
@@ -72,7 +71,7 @@ var HuggingFace = class {
    * Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text. Recommended model: dbmdz/bert-large-cased-finetuned-conll03-english
    */
   async tokenClassification(args, options) {
-    return HuggingFace.toArray(await this.request(args, options));
+    return HfInference.toArray(await this.request(args, options));
   }
   /**
    * This task is well known to translate text from one language to another. Recommended model: Helsinki-NLP/opus-mt-ru-en.
@@ -84,7 +83,7 @@ var HuggingFace = class {
    * This task is super useful to try out classification with zero code, you simply pass a sentence/paragraph and the possible labels for that sentence, and you get a result. Recommended model: facebook/bart-large-mnli.
    */
   async zeroShotClassification(args, options) {
-    return HuggingFace.toArray(await this.request(args, options));
+    return HfInference.toArray(await this.request(args, options));
   }
   /**
    * This task corresponds to any chatbot like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long range dependency or not. Recommended model: microsoft/DialoGPT-large.
@@ -149,11 +148,27 @@ var HuggingFace = class {
       binary: true
     });
   }
+  /**
+   * This task reads some text input and outputs an image.
+   * Recommended model: stabilityai/stable-diffusion-2
+   */
+  async textToImage(args, options) {
+    return await this.request(args, {
+      ...options,
+      blob: true
+    });
+  }
   async request(args, options) {
     const mergedOptions = { ...this.defaultOptions, ...options };
     const { model, ...otherArgs } = args;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    if (options?.binary && mergedOptions.wait_for_model) {
+      headers["X-Wait-For-Model"] = "true";
+    }
     const response = await fetch(`https://api-inference.huggingface.co/models/${model}`, {
-      headers: { Authorization: `Bearer ${this.apiKey}` },
+      headers,
       method: "POST",
       body: options?.binary ? args.data : JSON.stringify({
         ...otherArgs,
@@ -166,11 +181,19 @@ var HuggingFace = class {
         wait_for_model: true
       });
     }
-    const res = await response.json();
-    if (res.error) {
-      throw new Error(res.error);
+    let output;
+    if (options?.blob) {
+      if (!response.ok) {
+        throw new Error("An error occurred while fetching the blob");
+      }
+      return await response.arrayBuffer();
+    } else {
+      output = await response.json();
+      if (output.error) {
+        throw new Error(output.error);
+      }
     }
-    return res;
+    return output;
   }
   static toArray(obj) {
     if (Array.isArray(obj)) {
@@ -179,10 +202,7 @@ var HuggingFace = class {
     return [obj];
   }
 };
-
-// src/index.ts
-var src_default = HuggingFace;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  HuggingFace
+  HfInference
 });

package/dist/index.mjs

@@ -1,5 +1,5 @@
-// src/HuggingFace.ts
-var HuggingFace = class {
+// src/HfInference.ts
+var HfInference = class {
   apiKey;
   defaultOptions;
   constructor(apiKey, defaultOptions = {}) {
@@ -46,7 +46,7 @@ var HuggingFace = class {
    * Usually used for sentence parsing, either grammatical, or Named Entity Recognition (NER) to understand keywords contained within text. Recommended model: dbmdz/bert-large-cased-finetuned-conll03-english
    */
   async tokenClassification(args, options) {
-    return HuggingFace.toArray(await this.request(args, options));
+    return HfInference.toArray(await this.request(args, options));
   }
   /**
    * This task is well known to translate text from one language to another. Recommended model: Helsinki-NLP/opus-mt-ru-en.
@@ -58,7 +58,7 @@ var HuggingFace = class {
    * This task is super useful to try out classification with zero code, you simply pass a sentence/paragraph and the possible labels for that sentence, and you get a result. Recommended model: facebook/bart-large-mnli.
    */
   async zeroShotClassification(args, options) {
-    return HuggingFace.toArray(await this.request(args, options));
+    return HfInference.toArray(await this.request(args, options));
   }
   /**
    * This task corresponds to any chatbot like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long range dependency or not. Recommended model: microsoft/DialoGPT-large.
@@ -123,11 +123,27 @@ var HuggingFace = class {
       binary: true
     });
   }
+  /**
+   * This task reads some text input and outputs an image.
+   * Recommended model: stabilityai/stable-diffusion-2
+   */
+  async textToImage(args, options) {
+    return await this.request(args, {
+      ...options,
+      blob: true
+    });
+  }
   async request(args, options) {
     const mergedOptions = { ...this.defaultOptions, ...options };
     const { model, ...otherArgs } = args;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    if (options?.binary && mergedOptions.wait_for_model) {
+      headers["X-Wait-For-Model"] = "true";
+    }
     const response = await fetch(`https://api-inference.huggingface.co/models/${model}`, {
-      headers: { Authorization: `Bearer ${this.apiKey}` },
+      headers,
       method: "POST",
       body: options?.binary ? args.data : JSON.stringify({
         ...otherArgs,
@@ -140,11 +156,19 @@ var HuggingFace = class {
         wait_for_model: true
       });
     }
-    const res = await response.json();
-    if (res.error) {
-      throw new Error(res.error);
+    let output;
+    if (options?.blob) {
+      if (!response.ok) {
+        throw new Error("An error occurred while fetching the blob");
+      }
+      return await response.arrayBuffer();
+    } else {
+      output = await response.json();
+      if (output.error) {
+        throw new Error(output.error);
+      }
     }
-    return res;
+    return output;
   }
   static toArray(obj) {
     if (Array.isArray(obj)) {
@@ -153,10 +177,6 @@ var HuggingFace = class {
     return [obj];
   }
 };
-
-// src/index.ts
-var src_default = HuggingFace;
 export {
-  HuggingFace,
-  src_default as default
+  HfInference
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huggingface/inference",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "license": "MIT",
   "author": "Tim Mikeladze <tim.mikeladze@gmail.com>",
   "description": "Typescript wrapper for the Hugging Face Inference API",

package/src/{HuggingFace.ts → HfInference.ts}

@@ -485,7 +485,21 @@ export type AudioClassificationReturnValue = {
 
 export type AudioClassificationReturn = AudioClassificationReturnValue[];
 
-export class HuggingFace {
+export type TextToImageArgs = Args & {
+	/**
+	 * The text to generate an image from
+	 */
+	inputs: string;
+
+	/**
+	 * An optional negative prompt for the image generation
+	 */
+	negative_prompt?: string;
+};
+
+export type TextToImageReturn = ArrayBuffer;
+
+export class HfInference {
 	private readonly apiKey:         string;
 	private readonly defaultOptions: Options;
 
@@ -546,7 +560,7 @@ export class HuggingFace {
 		args: TokenClassificationArgs,
 		options?: Options
 	): Promise<TokenClassificationReturn> {
-		return HuggingFace.toArray(await this.request(args, options));
+		return HfInference.toArray(await this.request(args, options));
 	}
 
 	/**
@@ -563,7 +577,7 @@ export class HuggingFace {
 		args: ZeroShotClassificationArgs,
 		options?: Options
 	): Promise<ZeroShotClassificationReturn> {
-		return HuggingFace.toArray(await this.request(args, options));
+		return HfInference.toArray(await this.request(args, options));
 	}
 
 	/**
@@ -645,18 +659,39 @@ export class HuggingFace {
 		});
 	}
 
+	/**
+	 * This task reads some text input and outputs an image.
+	 * Recommended model: stabilityai/stable-diffusion-2
+	 */
+	public async textToImage(args: TextToImageArgs, options?: Options): Promise<TextToImageReturn> {
+		return await this.request(args, {
+			...options,
+			blob: true,
+		});
+	}
+
 	public async request(
 		args: Args & { data?: any },
 		options?: Options & {
 			binary?: boolean;
+			blob?:   boolean;
 		}
 	): Promise<any> {
 		const mergedOptions = { ...this.defaultOptions, ...options };
 		const { model, ...otherArgs } = args;
+
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+    }
+
+    if (options?.binary && mergedOptions.wait_for_model) {
+      headers["X-Wait-For-Model"] = "true";
+    }
+
 		const response = await fetch(`https://api-inference.huggingface.co/models/${model}`, {
-			headers: { Authorization: `Bearer ${this.apiKey}` },
-			method:  "POST",
-			body:    options?.binary
+			headers,
+			method: "POST",
+			body:   options?.binary
 				? args.data
 				: JSON.stringify({
 						...otherArgs,
@@ -671,11 +706,21 @@ export class HuggingFace {
 			});
 		}
 
-		const res = await response.json();
-		if (res.error) {
-			throw new Error(res.error);
+		let output;
+
+		if (options?.blob) {
+			if (!response.ok) {
+				throw new Error("An error occurred while fetching the blob");
+			}
+			return await response.arrayBuffer();
+		} else {
+			output = await response.json();
+			if (output.error) {
+				throw new Error(output.error);
+			}
 		}
-		return res;
+
+		return output;
 	}
 
 	private static toArray(obj: any): any[] {

package/src/index.ts

@@ -1,3 +1 @@
-import { HuggingFace } from "./HuggingFace";
-export * from "./HuggingFace";
-export default HuggingFace;
+export * from "./HfInference";