🤗 Hugging Face Inference API

A Typescript powered wrapper for the Hugging Face Inference API. Learn more about the Inference API at Hugging Face.

Install

1npm install huggingface
2
3yarn add huggingface
4
5pnpm add huggingface

Usage

❗Important note: Using an API key is optional to get started (simply provide a random string), however you will be rate limited eventually. Join Hugging Face and then visit access tokens to generate your API key.

Basic examples

1import HuggingFace from 'huggingface'
2
3const hf = new HuggingFace('your api key')
4
5// Natural Language
6
7await hf.fillMask({
8  model: 'bert-base-uncased',
9  inputs: '[MASK] world!'
10})
11
12await hf.summarization({
13  model: 'facebook/bart-large-cnn',
14  inputs:
15    'The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930.',
16  parameters: {
17    max_length: 100
18  }
19})
20
21await hf.questionAnswer({
22  model: 'deepset/roberta-base-squad2',
23  inputs: {
24    question: 'What is the capital of France?',
25    context: 'The capital of France is Paris.'
26  }
27})
28
29await hf.tableQuestionAnswer({
30  model: 'google/tapas-base-finetuned-wtq',
31  inputs: {
32    query: 'How many stars does the transformers repository have?',
33    table: {
34      Repository: ['Transformers', 'Datasets', 'Tokenizers'],
35      Stars: ['36542', '4512', '3934'],
36      Contributors: ['651', '77', '34'],
37      'Programming language': ['Python', 'Python', 'Rust, Python and NodeJS']
38    }
39  }
40})
41
42await hf.textClassification({
43  model: 'distilbert-base-uncased-finetuned-sst-2-english',
44  inputs: 'I like you. I love you.'
45})
46
47await hf.textGeneration({
48  model: 'gpt2',
49  inputs: 'The answer to the universe is'
50})
51
52await hf.tokenClassification({
53  model: 'dbmdz/bert-large-cased-finetuned-conll03-english',
54  inputs: 'My name is Sarah Jessica Parker but you can call me Jessica'
55})
56
57await hf.translation({
58  model: 't5-base',
59  inputs: 'My name is Wolfgang and I live in Berlin'
60})
61
62await hf.zeroShotClassification({
63  model: 'facebook/bart-large-mnli',
64  inputs: [
65    'Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!'
66  ],
67  parameters: { candidate_labels: ['refund', 'legal', 'faq'] }
68})
69
70await hf.conversational({
71  model: 'microsoft/DialoGPT-large',
72  inputs: {
73    past_user_inputs: ['Which movie is the best ?'],
74    generated_responses: ['It is Die Hard for sure.'],
75    text: 'Can you explain why ?'
76  }
77})
78
79await hf.featureExtraction({
80  model: 'sentence-transformers/paraphrase-xlm-r-multilingual-v1',
81  inputs: {
82    source_sentence: 'That is a happy person',
83    sentences: [
84      'That is a happy dog',
85      'That is a very happy person',
86      'Today is a sunny day'
87    ]
88  }
89})
90
91// Audio
92
93await hf.automaticSpeechRecognition({
94  model: 'facebook/wav2vec2-large-960h-lv60-self',
95  data: readFileSync('test/sample1.flac')
96})
97
98await hf.audioClassification({
99  model: 'superb/hubert-large-superb-er',
100  data: readFileSync('test/sample1.flac')
101})
102
103// Computer Vision
104
105await hf.imageClassification({
106  data: readFileSync('test/cheetah.png'),
107  model: 'google/vit-base-patch16-224'
108})
109
110await hf.objectDetection({
111  data: readFileSync('test/cats.png'),
112  model: 'facebook/detr-resnet-50'
113})
114
115await hf.imageSegmentation({
116  data: readFileSync('test/cats.png'),
117  model: 'facebook/detr-resnet-50-panoptic'
118})

Supported APIs

Natural Language Processing

• Fill mask
• Summarization
• Question answering
• Table question answering
• Text classification
• Text generation
• Text2Text generation
• Token classification
• Named entity recognition
• Translation
• Zero-shot classification
• Conversational
• Feature extraction

Audio

• Automatic speech recognition
• Audio classification

Computer Vision

• Image classification
• Object detection
• Image segmentation

Running tests

1HF_API_KEY="your api key" yarn test

Options

1export declare class HuggingFace {
2  private readonly apiKey
3  private readonly defaultOptions
4  constructor(apiKey: string, defaultOptions?: Options)
5  /**
6   * Tries to fill in a hole with a missing word (token to be precise). That’s the base task for BERT models.
7   */
8  fillMask(args: FillMaskArgs, options?: Options): Promise<FillMaskReturn>
9  /**
10   * This task is well known to summarize longer text into shorter text. Be careful, some models have a maximum length of input. That means that the summary cannot handle full books for instance. Be careful when choosing your model.
11   */
12  summarization(
13    args: SummarizationArgs,
14    options?: Options
15  ): Promise<SummarizationReturn>
16  /**
17   * Want to have a nice know-it-all bot that can answer any question?. Recommended model: deepset/roberta-base-squad2
18   */
19  questionAnswer(
20    args: QuestionAnswerArgs,
21    options?: Options
22  ): Promise<QuestionAnswerReturn>
23  /**
24   * Don’t know SQL? Don’t want to dive into a large spreadsheet? Ask questions in plain english! Recommended model: google/tapas-base-finetuned-wtq.
25   */
26  tableQuestionAnswer(
27    args: TableQuestionAnswerArgs,
28    options?: Options
29  ): Promise<TableQuestionAnswerReturn>
30  /**
31   * Usually used for sentiment-analysis this will output the likelihood of classes of an input. Recommended model: distilbert-base-uncased-finetuned-sst-2-english
32   */
33  textClassification(
34    args: TextClassificationArgs,
35    options?: Options
36  ): Promise<TextClassificationReturn>
37  /**
38   * Use to continue text from a prompt. This is a very generic task. Recommended model: gpt2 (it’s a simple model, but fun to play with).
39   */
40  textGeneration(
41    args: TextGenerationArgs,
42    options?: Options
43  ): Promise<TextGenerationReturn>
44  /**
45   * 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
46   */
47  tokenClassification(
48    args: TokenClassificationArgs,
49    options?: Options
50  ): Promise<TokenClassificationReturn>
51  /**
52   * This task is well known to translate text from one language to another. Recommended model: Helsinki-NLP/opus-mt-ru-en.
53   */
54  translation(
55    args: TranslationArgs,
56    options?: Options
57  ): Promise<TranslationReturn>
58  /**
59   * 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.
60   */
61  zeroShotClassification(
62    args: ZeroShotClassificationArgs,
63    options?: Options
64  ): Promise<ZeroShotClassificationReturn>
65  /**
66   * 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.
67   *
68   */
69  conversational(
70    args: ConversationalArgs,
71    options?: Options
72  ): Promise<ConversationalReturn>
73  /**
74   * This task reads some text and outputs raw float values, that are usually consumed as part of a semantic database/semantic search.
75   */
76  featureExtraction(
77    args: FeatureExtractionArgs,
78    options?: Options
79  ): Promise<FeatureExtractionReturn>
80  /**
81   * This task reads some audio input and outputs the said words within the audio files.
82   * Recommended model (english language): facebook/wav2vec2-large-960h-lv60-self
83   */
84  automaticSpeechRecognition(
85    args: AutomaticSpeechRecognitionArgs,
86    options?: Options
87  ): Promise<AutomaticSpeechRecognitionReturn>
88  /**
89   * This task reads some audio input and outputs the likelihood of classes.
90   * Recommended model:  superb/hubert-large-superb-er
91   */
92  audioClassification(
93    args: AudioClassificationArgs,
94    options?: Options
95  ): Promise<AudioClassificationReturn>
96  /**
97   * This task reads some image input and outputs the likelihood of classes.
98   * Recommended model: google/vit-base-patch16-224
99   */
100  imageClassification(
101    args: ImageClassificationArgs,
102    options?: Options
103  ): Promise<ImageClassificationReturn>
104  /**
105   * This task reads some image input and outputs the likelihood of classes & bounding boxes of detected objects.
106   * Recommended model: facebook/detr-resnet-50
107   */
108  objectDetection(
109    args: ObjectDetectionArgs,
110    options?: Options
111  ): Promise<ObjectDetectionReturn>
112  /**
113   * This task reads some image input and outputs the likelihood of classes & bounding boxes of detected objects.
114   * Recommended model: facebook/detr-resnet-50-panoptic
115   */
116  imageSegmentation(
117    args: ImageSegmentationArgs,
118    options?: Options
119  ): Promise<ImageSegmentationReturn>
120  request(
121    args: Args & {
122      data?: any
123    },
124    options?: Options & {
125      binary?: boolean
126    }
127  ): Promise<any>
128  private static toArray
129}
130
131export declare type Options = {
132  /**
133   * (Default: false). Boolean to use GPU instead of CPU for inference (requires Startup plan at least).
134   */
135  use_gpu?: boolean
136  /**
137   * (Default: true). Boolean. There is a cache layer on the inference API to speedup requests we have already seen. Most models can use those results as is as models are deterministic (meaning the results will be the same anyway). However if you use a non deterministic model, you can set this parameter to prevent the caching mechanism from being used resulting in a real new query.
138   */
139  use_cache?: boolean
140  /**
141   * (Default: false) Boolean. If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places.
142   */
143  wait_for_model?: boolean
144  /**
145   * (Default: true) Boolean. If a request 503s and wait_for_model is set to false, the request will be retried with the same parameters but with wait_for_model set to true.
146   */
147  retry_on_error?: boolean
148}
149export declare type Args = {
150  model: string
151}
152export declare type FillMaskArgs = Args & {
153  inputs: string
154}
155export declare type FillMaskReturn = {
156  /**
157   * The probability for this token.
158   */
159  score: number
160  /**
161   * The id of the token
162   */
163  token: number
164  /**
165   * The string representation of the token
166   */
167  token_str: string
168  /**
169   * The actual sequence of tokens that ran against the model (may contain special tokens)
170   */
171  sequence: string
172}[]
173export declare type SummarizationArgs = Args & {
174  /**
175   * A string to be summarized
176   */
177  inputs: string
178  parameters?: {
179    /**
180     * (Default: None). Integer to define the minimum length in tokens of the output summary.
181     */
182    min_length?: number
183    /**
184     * (Default: None). Integer to define the maximum length in tokens of the output summary.
185     */
186    max_length?: number
187    /**
188     * (Default: None). Integer to define the top tokens considered within the sample operation to create new text.
189     */
190    top_k?: number
191    /**
192     * (Default: None). Float to define the tokens that are within the sample operation of text generation. Add tokens in the sample for more probable to least probable until the sum of the probabilities is greater than top_p.
193     */
194    top_p?: number
195    /**
196     * (Default: 1.0). Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability.
197     */
198    temperature?: number
199    /**
200     * (Default: None). Float (0.0-100.0). The more a token is used within generation the more it is penalized to not be picked in successive generation passes.
201     */
202    repetition_penalty?: number
203    /**
204     * (Default: None). Float (0-120.0). The amount of time in seconds that the query should take maximum. Network can cause some overhead so it will be a soft limit.
205     */
206    max_time?: number
207  }
208}
209export declare type SummarizationReturn = {
210  /**
211   * The string after translation
212   */
213  summary_text: string
214}
215export declare type QuestionAnswerArgs = Args & {
216  inputs: {
217    question: string
218    context: string
219  }
220}
221export declare type QuestionAnswerReturn = {
222  /**
223   * A string that’s the answer within the text.
224   */
225  answer: string
226  /**
227   * A float that represents how likely that the answer is correct
228   */
229  score: number
230  /**
231   * The index (string wise) of the start of the answer within context.
232   */
233  start: number
234  /**
235   * The index (string wise) of the stop of the answer within context.
236   */
237  end: number
238}
239export declare type TableQuestionAnswerArgs = Args & {
240  inputs: {
241    /**
242     * The query in plain text that you want to ask the table
243     */
244    query: string
245    /**
246     * A table of data represented as a dict of list where entries are headers and the lists are all the values, all lists must have the same size.
247     */
248    table: Record<string, string[]>
249  }
250}
251export declare type TableQuestionAnswerReturn = {
252  /**
253   * The plaintext answer
254   */
255  answer: string
256  /**
257   * a list of coordinates of the cells referenced in the answer
258   */
259  coordinates: number[][]
260  /**
261   * A list of coordinates of the cells contents
262   */
263  cells: string[]
264  /**
265   * The aggregator used to get the answer
266   */
267  aggregator: string
268}
269export declare type TextClassificationArgs = Args & {
270  /**
271   * A string to be classified
272   */
273  inputs: string
274}
275export declare type TextClassificationReturn = {
276  /**
277   * The label for the class (model specific)
278   */
279  label: string
280  /**
281   * A floats that represents how likely is that the text belongs to this class.
282   */
283  score: number
284}[]
285export declare type TextGenerationArgs = Args & {
286  /**
287   * A string to be generated from
288   */
289  inputs: string
290  parameters?: {
291    /**
292     * (Default: None). Integer to define the top tokens considered within the sample operation to create new text.
293     */
294    top_k?: number
295    /**
296     * (Default: None). Float to define the tokens that are within the sample operation of text generation. Add tokens in the sample for more probable to least probable until the sum of the probabilities is greater than top_p.
297     */
298    top_p?: number
299    /**
300     * (Default: 1.0). Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability.
301     */
302    temperature?: number
303    /**
304     * (Default: None). Float (0.0-100.0). The more a token is used within generation the more it is penalized to not be picked in successive generation passes.
305     */
306    repetition_penalty?: number
307    /**
308     * (Default: None). Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated.
309     */
310    max_new_tokens?: number
311    /**
312     * (Default: None). Float (0-120.0). The amount of time in seconds that the query should take maximum. Network can cause some overhead so it will be a soft limit. Use that in combination with max_new_tokens for best results.
313     */
314    max_time?: number
315    /**
316     * (Default: True). Bool. If set to False, the return results will not contain the original query making it easier for prompting.
317     */
318    return_full_text?: boolean
319    /**
320     * (Default: 1). Integer. The number of proposition you want to be returned.
321     */
322    num_return_sequences?: number
323    /**
324     * (Optional: True). Bool. Whether or not to use sampling, use greedy decoding otherwise.
325     */
326    do_sample?: boolean
327  }
328}
329export declare type TextGenerationReturn = {
330  /**
331   * The continuated string
332   */
333  generated_text: string
334}
335export declare type TokenClassificationArgs = Args & {
336  /**
337   * A string to be classified
338   */
339  inputs: string
340  parameters?: {
341    /**
342     * (Default: simple). There are several aggregation strategies:
343     *
344     * none: Every token gets classified without further aggregation.
345     *
346     * simple: Entities are grouped according to the default schema (B-, I- tags get merged when the tag is similar).
347     *
348     * first: Same as the simple strategy except words cannot end up with different tags. Words will use the tag of the first token when there is ambiguity.
349     *
350     * average: Same as the simple strategy except words cannot end up with different tags. Scores are averaged across tokens and then the maximum label is applied.
351     *
352     * max: Same as the simple strategy except words cannot end up with different tags. Word entity will be the token with the maximum score.
353     */
354    aggregation_strategy?: 'none' | 'simple' | 'first' | 'average' | 'max'
355  }
356}
357export declare type TokenClassificationReturnValue = {
358  /**
359   * The type for the entity being recognized (model specific).
360   */
361  entity_group: string
362  /**
363   * How likely the entity was recognized.
364   */
365  score: number
366  /**
367   * The string that was captured
368   */
369  word: string
370  /**
371   * The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
372   */
373  start: number
374  /**
375   * The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
376   */
377  end: number
378}
379export declare type TokenClassificationReturn = TokenClassificationReturnValue[]
380export declare type TranslationArgs = Args & {
381  /**
382   * A string to be translated
383   */
384  inputs: string
385}
386export declare type TranslationReturn = {
387  /**
388   * The string after translation
389   */
390  translation_text: string
391}
392export declare type ZeroShotClassificationArgs = Args & {
393  /**
394   * a string or list of strings
395   */
396  inputs: string | string[]
397  parameters: {
398    /**
399     * a list of strings that are potential classes for inputs. (max 10 candidate_labels, for more, simply run multiple requests, results are going to be misleading if using too many candidate_labels anyway. If you want to keep the exact same, you can simply run multi_label=True and do the scaling on your end.
400     */
401    candidate_labels: string[]
402    /**
403     * (Default: false) Boolean that is set to True if classes can overlap
404     */
405    multi_label?: boolean
406  }
407}
408export declare type ZeroShotClassificationReturnValue = {
409  sequence: string
410  labels: string[]
411  scores: number[]
412}
413export declare type ZeroShotClassificationReturn =
414  ZeroShotClassificationReturnValue[]
415export declare type ConversationalArgs = Args & {
416  inputs: {
417    /**
418     * The last input from the user in the conversation.
419     */
420    text: string
421    /**
422     * A list of strings corresponding to the earlier replies from the model.
423     */
424    generated_responses?: string[]
425    /**
426     * 	A list of strings corresponding to the earlier replies from the user. Should be of the same length of generated_responses.
427     */
428    past_user_inputs?: string[]
429  }
430  parameters?: {
431    /**
432     * (Default: None). Integer to define the minimum length in tokens of the output summary.
433     */
434    min_length?: number
435    /**
436     * (Default: None). Integer to define the maximum length in tokens of the output summary.
437     */
438    max_length?: number
439    /**
440     * (Default: None). Integer to define the top tokens considered within the sample operation to create new text.
441     */
442    top_k?: number
443    /**
444     * (Default: None). Float to define the tokens that are within the sample operation of text generation. Add tokens in the sample for more probable to least probable until the sum of the probabilities is greater than top_p.
445     */
446    top_p?: number
447    /**
448     * (Default: 1.0). Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability.
449     */
450    temperature?: number
451    /**
452     * (Default: None). Float (0.0-100.0). The more a token is used within generation the more it is penalized to not be picked in successive generation passes.
453     */
454    repetition_penalty?: number
455    /**
456     * (Default: None). Float (0-120.0). The amount of time in seconds that the query should take maximum. Network can cause some overhead so it will be a soft limit.
457     */
458    max_time?: number
459  }
460}
461export declare type ConversationalReturn = {
462  generated_text: string
463  conversation: {
464    generated_responses: string[]
465    past_user_inputs: string[]
466  }
467  warnings: string[]
468}
469export declare type FeatureExtractionArgs = Args & {
470  /**
471   * The inputs vary based on the model. For example when using sentence-transformers/paraphrase-xlm-r-multilingual-v1 the inputs will look like this:
472   *
473   *  inputs: {
474   *    "source_sentence": "That is a happy person",
475   *    "sentences": ["That is a happy dog", "That is a very happy person", "Today is a sunny day"]
476   */
477  inputs: Record<string, any> | Record<string, any>[]
478}
479/**
480 * Returned values are a list of floats, or a list of list of floats (depending on if you sent a string or a list of string, and if the automatic reduction, usually mean_pooling for instance was applied for you or not. This should be explained on the model's README.
481 */
482export declare type FeatureExtractionReturn = (number | number[])[]
483export declare type ImageClassificationArgs = Args & {
484  /**
485   * Binary image data
486   */
487  data: any
488}
489export declare type ImageClassificationReturnValue = {
490  /**
491   * The label for the class (model specific)
492   */
493  score: number
494  /**
495   * A float that represents how likely it is that the image file belongs to this class.
496   */
497  label: string
498}
499export declare type ImageClassificationReturn = ImageClassificationReturnValue[]
500export declare type ObjectDetectionArgs = Args & {
501  /**
502   * Binary image data
503   */
504  data: any
505}
506export declare type ObjectDetectionReturnValue = {
507  /**
508   * A float that represents how likely it is that the detected object belongs to the given class.
509   */
510  score: number
511  /**
512   * The label for the class (model specific) of a detected object.
513   */
514  label: string
515  /**
516   * A dict (with keys [xmin,ymin,xmax,ymax]) representing the bounding box of a detected object.
517   */
518  box: {
519    xmin: number
520    ymin: number
521    xmax: number
522    ymax: number
523  }
524}
525export declare type ObjectDetectionReturn = ObjectDetectionReturnValue[]
526export declare type ImageSegmentationArgs = Args & {
527  /**
528   * Binary image data
529   */
530  data: any
531}
532export declare type ImageSegmentationReturnValue = {
533  /**
534   * A float that represents how likely it is that the detected object belongs to the given class.
535   */
536  score: number
537  /**
538   * The label for the class (model specific) of a segment.
539   */
540  label: string
541  /**
542   * A str (base64 str of a single channel black-and-white img) representing the mask of a segment.
543   */
544  mask: string
545}
546export declare type ImageSegmentationReturn = ImageSegmentationReturnValue[]
547export declare type AutomaticSpeechRecognitionArgs = Args & {
548  /**
549   * Binary audio data
550   */
551  data: any
552}
553export declare type AutomaticSpeechRecognitionReturn = {
554  /**
555   * The text that was recognized from the audio
556   */
557  text: string
558}
559export declare type AudioClassificationArgs = Args & {
560  /**
561   * Binary audio data
562   */
563  data: any
564}
565export declare type AudioClassificationReturnValue = {
566  /**
567   * The label for the class (model specific)
568   */
569  label: string
570  /**
571   * A float that represents how likely it is that the audio file belongs to this class.
572   */
573  score: number
574}
575export declare type AudioClassificationReturn = AudioClassificationReturnValue[]