you need to learn all this docu to generate:



"""

Serverless Inference API

Instant Access to thousands of ML Models for Fast Prototyping

Explore the most popular models for text, image, speech, and more — all with a simple API request. Build, test, and experiment without worrying about infrastructure or setup.
Why use the Inference API?

The Serverless Inference API offers a fast and free way to explore thousands of models for a variety of tasks. Whether you’re prototyping a new application or experimenting with ML capabilities, this API gives you instant access to high-performing models across multiple domains:

    Text Generation: Including large language models and tool-calling prompts, generate and experiment with high-quality responses.
    Image Generation: Easily create customized images, including LoRAs for your own styles.
    Document Embeddings: Build search and retrieval systems with SOTA embeddings.
    Classical AI Tasks: Ready-to-use models for text classification, image classification, speech recognition, and more.

⚡ Fast and Free to Get Started: The Inference API is free with higher rate limits for PRO users. For production needs, explore Inference Endpoints for dedicated resources, autoscaling, advanced security features, and more.
Key Benefits

    🚀 Instant Prototyping: Access powerful models without setup.
    🎯 Diverse Use Cases: One API for text, image, and beyond.
    🔧 Developer-Friendly: Simple requests, fast responses.

Main Features

    Leverage over 800,000+ models from different open-source libraries (transformers, sentence transformers, adapter transformers, diffusers, timm, etc.).
    Use models for a variety of tasks, including text generation, image generation, document embeddings, NER, summarization, image classification, and more.
    Accelerate your prototyping by using GPU-powered models.
    Run very large models that are challenging to deploy in production.
    Production-grade platform without the hassle: built-in automatic scaling, load balancing and caching.

Contents

The documentation is organized into two sections:

    Getting Started Learn the basics of how to use the Inference API.
    API Reference Dive into task-specific settings and parameters.Getting Started

The Serverless Inference API allows you to easily do inference on a wide range of models and tasks. You can do requests with your favorite tools (Python, cURL, etc). We also provide a Python SDK (huggingface_hub) to make it even easier.

We’ll do a minimal example using a sentiment classification model. Please visit task-specific parameters and further documentation in our API Reference.
Getting a Token

Using the Serverless Inference API requires passing a user token in the request headers. You can get a token by signing up on the Hugging Face website and then going to the tokens page. We recommend creating a fine-grained token with the scope to Make calls to the serverless Inference API.

For more details about user tokens, check out this guide.
cURL

curl 'https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest' \
-H "Authorization: Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H 'Content-Type: application/json' \
-d '{"inputs": "Today is a great day"}'

Python

You can use the requests library to make a request to the Inference API.

import requests

API_URL = "https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest"
headers = {"Authorization": "Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
payload = {
    "inputs": "Today is a great day",
}

response = requests.post(API_URL, headers=headers, json=payload)
response.json()

Hugging Face also provides a InferenceClient that handles inference for you. Make sure to install it with pip install huggingface_hub first.

from huggingface_hub import InferenceClient

client = InferenceClient(
    "cardiffnlp/twitter-roberta-base-sentiment-latest",
    token="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

client.text_classification("Today is a great day")

JavaScript

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,
                "Content-Type": "application/json",
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({inputs: "Today is a great day"}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

Hugging Face also provides a HfInference client that handles inference. Make sure to install it with npm install @huggingface/inference first.

import { HfInference } from "@huggingface/inference";

const inference = new HfInference("hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

const result = await inference.textClassification({
    model: "cardiffnlp/twitter-roberta-base-sentiment-latest",
    inputs: "Today is a great day",
});

console.log(result);

Next Steps

Now that you know the basics, you can explore the API Reference to learn more about task-specific settings and parameters.Supported Models

Given the fast-paced nature of the open ML ecosystem, the Inference API exposes models that have large community interest and are in active use (based on recent likes, downloads, and usage). Because of this, deployed models can be swapped without prior notice. The Hugging Face stack aims to keep all the latest popular models warm and ready to use.

You can find:

    Warm models: models ready to be used.
    Cold models: models that are not loaded but can be used.
    Frozen models: models that currently can’t be run with the API.

What do I get with a PRO subscription?

In addition to thousands of public models available in the Hub, PRO and Enterprise users get higher rate limits and free access to the following models:
Model 	Size 	Supported Context Length 	Use
Meta Llama 3.1 Instruct 	8B, 70B 	70B: 32k tokens / 8B: 8k tokens 	High quality multilingual chat model with large context length
Meta Llama 3 Instruct 	8B, 70B 	8k tokens 	One of the best chat models
Meta Llama Guard 3 	8B 	4k tokens 	
Llama 2 Chat 	7B, 13B, 70B 	4k tokens 	One of the best conversational models
DeepSeek Coder v2 	236B 	16k tokens 	A model with coding capabilities.
Bark 	0.9B 	- 	Text to audio generation

This list is not exhaustive and might be updated in the future.
Running Private Models

The free Serverless API is designed to run popular public models. If you have a private model, you can use Inference Endpoints to deploy it.Rate Limits

The Inference API has rate limits based on the number of requests. These rate limits are subject to change in the future to be compute-based or token-based.

Serverless API is not meant to be used for heavy production applications. If you need higher rate limits, consider Inference Endpoints to have dedicated resources.

You need to be authenticated (passing a token or through your browser) to use the Inference API.
User Tier 	Rate Limit
Signed-up Users 	1,000 requests per day
PRO and Enterprise Users 	20,000 requests per day
< > Update on GitHub

Supported Models
←Supported Models
SecuritySecurity & Compliance

The Inference API is not designed for heavy production requirements. For production needs, explore Inference Endpoints for dedicated resources, autoscaling, advanced security features, and more.
Data Security/Privacy

Hugging Face does not store any user data for training purposes. Tokens sent to the API might be stored in a short-term (few minutes) cache mechanism to speed-up repeated requests. Logs are stored for debugging for up to 30 days. Any additional data in terms of user data or tokens are not stored.

Serverless Inference API use TLS/SSL to encrypt the data in transit.
Hub Security

The Hugging Face Hub, which Serverless Inference API is part, is SOC2 Type 2 certified. For more on Hub security: https://huggingface.co/docs/hub/security
< > Update on GitHub

Rate Limits
←Rate Limits
Parameters→Parameters
Additional Options
Caching

There is a cache layer on the inference API to speed up requests when the inputs are exactly the same. Many models, such as classifiers and embedding models, can use those results as is if they are deterministic, meaning the results will be the same. However, if you use a nondeterministic model, you can disable the cache mechanism from being used, resulting in a real new query.

To do this, you can add x-use-cache:false to the request headers. For example

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/MODEL_ID",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_***`,
                "Content-Type": "application/json",
+               "x-use-cache": "false"
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({
    inputs: "Can you please let us know more details about your "
}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

Wait for the model

When a model is warm, it is ready to be used and you will get a response relatively quickly. However, some models are cold and need to be loaded before they can be used. In that case, you will get a 503 error. Rather than doing many requests until it’s loaded, you can wait for the model to be loaded by adding x-wait-for-model:true to the request headers. We suggest to only use this flag to wait for the model to be loaded when you are sure that the model is cold. That means, first try the request without this flag and only if you get a 503 error, try again with this flag.

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/MODEL_ID",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_***`,
                "Content-Type": "application/json",
+               "x-wait-for-model": "true"
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({
    inputs: "Can you please let us know more details about your "
}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

< > Update on GitHub

Parameters
←Security
Audio ClassificationAudio Classification

Audio classification is the task of assigning a label or class to a given audio.

Example applications:

    Recognizing which command a user is giving
    Identifying a speaker
    Detecting the genre of a song

For more details about the audio-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition: An emotion recognition model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("sample1.flac").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input audio data as a base64-encoded string. If no parameters are provided, you can also provide the audio data as a raw bytes payload.
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Audio Classification
←Parameters
Automatic Speech RecognitionAutomatic Speech Recognition

Automatic Speech Recognition (ASR), also known as Speech to Text (STT), is the task of transcribing a given audio to text.

Example applications:

    Transcribing a podcast
    Building a voice assistant
    Generating subtitles for a video

For more details about the automatic-speech-recognition task, check out its dedicated page! You will find examples and related materials.
Recommended models

    openai/whisper-large-v3: A powerful ASR model by OpenAI.
    nvidia/canary-1b: A powerful multilingual ASR and Speech Translation model by Nvidia.
    pyannote/speaker-diarization-3.1: Powerful speaker diarization model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/openai/whisper-large-v3",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("sample1.flac").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input audio data as a base64-encoded string. If no parameters are provided, you can also provide the audio data as a raw bytes payload.
parameters 	object 	
        return_timestamps 	boolean 	Whether to output corresponding timestamps with the generated text
        generation_parameters 	object 	
                temperature 	number 	The value used to modulate the next token probabilities.
                top_k 	integer 	The number of highest probability vocabulary tokens to keep for top-k-filtering.
                top_p 	number 	If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation.
                typical_p 	number 	Local typicality measures how similar the conditional probability of predicting a target token next is to the expected conditional probability of predicting a random token next, given the partial text already generated. If set to float < 1, the smallest set of the most locally typical tokens with probabilities that add up to typical_p or higher are kept for generation. See this paper for more details.
                epsilon_cutoff 	number 	If set to float strictly between 0 and 1, only tokens with a conditional probability greater than epsilon_cutoff will be sampled. In the paper, suggested values range from 3e-4 to 9e-4, depending on the size of the model. See Truncation Sampling as Language Model Desmoothing for more details.
                eta_cutoff 	number 	Eta sampling is a hybrid of locally typical sampling and epsilon sampling. If set to float strictly between 0 and 1, a token is only considered if it is greater than either eta_cutoff or sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))). The latter term is intuitively the expected next token probability, scaled by sqrt(eta_cutoff). In the paper, suggested values range from 3e-4 to 2e-3, depending on the size of the model. See Truncation Sampling as Language Model Desmoothing for more details.
                max_length 	integer 	The maximum length (in tokens) of the generated text, including the input.
                max_new_tokens 	integer 	The maximum number of tokens to generate. Takes precedence over max_length.
                min_length 	integer 	The minimum length (in tokens) of the generated text, including the input.
                min_new_tokens 	integer 	The minimum number of tokens to generate. Takes precedence over min_length.
                do_sample 	boolean 	Whether to use sampling instead of greedy decoding when generating new tokens.
                early_stopping 	enum 	Possible values: never, true, false.
                num_beams 	integer 	Number of beams to use for beam search.
                num_beam_groups 	integer 	Number of groups to divide num_beams into in order to ensure diversity among different groups of beams. See this paper for more details.
                penalty_alpha 	number 	The value balances the model confidence and the degeneration penalty in contrastive search decoding.
                use_cache 	boolean 	Whether the model should use the past last key/values attentions to speed up decoding

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
text 	string 	The recognized text.
chunks 	object[] 	When returnTimestamps is enabled, chunks contains a list of audio chunks identified by the model.
        text 	string 	A chunk of text identified by the model
        timestamps 	number[] 	The start and end timestamps corresponding with the text
< > Update on GitHub

Audio Classification
←Audio Classification
Chat Completion→Chat Completion

Generate a response given a list of messages in a conversational context, supporting both conversational Language Models (LLMs) and conversational Vision-Language Models (VLMs). This is a subtask of text-generation and image-text-to-text.
Recommended models
Conversational Large Language Models (LLMs)

    google/gemma-2-2b-it: A text-generation model trained to follow instructions.
    meta-llama/Meta-Llama-3.1-8B-Instruct: Very powerful text generation model trained to follow instructions.
    microsoft/Phi-3-mini-4k-instruct: Small yet powerful text generation model.
    Qwen/Qwen2.5-7B-Instruct: Strong text generation model to follow instructions.

Conversational Vision-Language Models (VLMs)

    meta-llama/Llama-3.2-11B-Vision-Instruct: Powerful vision language model with great visual understanding and reasoning capabilities.
    Qwen/Qwen2-VL-7B-Instruct: Strong image-text-to-text model.

API Playground

For Chat Completion models, we provide an interactive UI Playground for easier testing:

    Quickly iterate on your prompts from the UI.
    Set and override system, assistant and user messages.
    Browse and select models currently available on the Inference API.
    Compare the output of two models side-by-side.
    Adjust requests parameters from the UI.
    Easily switch between UI view and code snippets.

Access the Inference UI Playground and start exploring: https://huggingface.co/playground
Using the API

The API supports:

    Using the chat completion API compatible with the OpenAI SDK.
    Using grammars, constraints, and tools.
    Streaming the output

Code snippet example for conversational LLMs

Using huggingface.js:

import { HfInference } from "@huggingface/inference";

const client = new HfInference("hf_***");

let out = "";

const stream = client.chatCompletionStream({
	model: "google/gemma-2-2b-it",
	messages: [
		{
			role: "user",
			content: "What is the capital of France?"
		}
	],
	max_tokens: 500
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

Using openai:

import { OpenAI } from "openai";

const client = new OpenAI({
	baseURL: "https://api-inference.huggingface.co/v1/",
    apiKey: "hf_***"
});

let out = "";

const stream = await client.chat.completions.create({
	model: "google/gemma-2-2b-it",
	messages: [
		{
			role: "user",
			content: "What is the capital of France?"
		}
	],
	max_tokens: 500,
	stream: true,
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

To use the JavaScript client, see huggingface.js’s package reference.
Code snippet example for conversational VLMs

Using huggingface.js:

import { HfInference } from "@huggingface/inference";

const client = new HfInference("hf_***");

let out = "";

const stream = client.chatCompletionStream({
	model: "meta-llama/Llama-3.2-11B-Vision-Instruct",
	messages: [
		{
			role: "user",
			content: [
				{
					type: "text",
					text: "Describe this image in one sentence."
				},
				{
					type: "image_url",
					image_url: {
						url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
					}
				}
			]
		}
	],
	max_tokens: 500
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

Using openai:

import { OpenAI } from "openai";

const client = new OpenAI({
	baseURL: "https://api-inference.huggingface.co/v1/",
    apiKey: "hf_***"
});

let out = "";

const stream = await client.chat.completions.create({
	model: "meta-llama/Llama-3.2-11B-Vision-Instruct",
	messages: [
		{
			role: "user",
			content: [
				{
					type: "text",
					text: "Describe this image in one sentence."
				},
				{
					type: "image_url",
					image_url: {
						url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
					}
				}
			]
		}
	],
	max_tokens: 500,
	stream: true,
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
frequency_penalty 	number 	Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.
logprobs 	boolean 	Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.
max_tokens 	integer 	The maximum number of tokens that can be generated in the chat completion.
messages* 	object[] 	A list of messages comprising the conversation so far.
        content* 	unknown 	One of the following:
                 (#1) 	string 	
                 (#2) 	object[] 	
                         (#1) 	object 	
                                text* 	string 	
                                type* 	enum 	Possible values: text.
                         (#2) 	object 	
                                image_url* 	object 	
                                        url* 	string 	
                                type* 	enum 	Possible values: image_url.
        name 	string 	
        role* 	string 	
presence_penalty 	number 	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics
response_format 	unknown 	One of the following:
         (#1) 	object 	
                type* 	enum 	Possible values: json.
                value* 	unknown 	A string that represents a JSON Schema. JSON Schema is a declarative language that allows to annotate JSON documents with types and descriptions.
         (#2) 	object 	
                type* 	enum 	Possible values: regex.
                value* 	string 	
seed 	integer 	
stop 	string[] 	Up to 4 sequences where the API will stop generating further tokens.
stream 	boolean 	
stream_options 	object 	
        include_usage* 	boolean 	If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value.
temperature 	number 	What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.
tool_choice 	unknown 	One of the following:
         (#1) 	enum 	Possible values: auto.
         (#2) 	enum 	Possible values: none.
         (#3) 	enum 	Possible values: required.
         (#4) 	object 	
                function* 	object 	
                        name* 	string 	
tool_prompt 	string 	A prompt to be appended before the tools
tools 	object[] 	A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
        function* 	object 	
                arguments* 	unknown 	
                description 	string 	
                name* 	string 	
        type* 	string 	
top_logprobs 	integer 	An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.
top_p 	number 	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
choices 	object[] 	
        finish_reason 	string 	
        index 	integer 	
        logprobs 	object 	
                content 	object[] 	
                        logprob 	number 	
                        token 	string 	
                        top_logprobs 	object[] 	
                                logprob 	number 	
                                token 	string 	
        message 	unknown 	One of the following:
                 (#1) 	object 	
                        content 	string 	
                        role 	string 	
                 (#2) 	object 	
                        role 	string 	
                        tool_calls 	object[] 	
                                function 	object 	
                                        arguments 	unknown 	
                                        description 	string 	
                                        name 	string 	
                                id 	string 	
                                type 	string 	
created 	integer 	
id 	string 	
model 	string 	
system_fingerprint 	string 	
usage 	object 	
        completion_tokens 	integer 	
        prompt_tokens 	integer 	
        total_tokens 	integer 	

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
Body 		
choices 	object[] 	
        delta 	unknown 	One of the following:
                 (#1) 	object 	
                        content 	string 	
                        role 	string 	
                 (#2) 	object 	
                        role 	string 	
                        tool_calls 	object 	
                                function 	object 	
                                        arguments 	string 	
                                        name 	string 	
                                id 	string 	
                                index 	integer 	
                                type 	string 	
        finish_reason 	string 	
        index 	integer 	
        logprobs 	object 	
                content 	object[] 	
                        logprob 	number 	
                        token 	string 	
                        top_logprobs 	object[] 	
                                logprob 	number 	
                                token 	string 	
created 	integer 	
id 	string 	
model 	string 	
system_fingerprint 	string 	
usage 	object 	
        completion_tokens 	integer 	
        prompt_tokens 	integer 	
        total_tokens 	integer 	
< > Update on GitHub

Chat Completion
←Automatic Speech Recognition
Feature Extraction→Feature Extraction

Feature extraction is the task of converting a text into a vector (often called “embedding”).

Example applications:

    Retrieving the most relevant documents for a query (for RAG applications).
    Reranking a list of documents based on their similarity to a query.
    Calculating the similarity between two sentences.

For more details about the feature-extraction task, check out its dedicated page! You will find examples and related materials.
Recommended models

    thenlper/gte-large: A powerful feature extraction model for natural language processing tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/thenlper/gte-large",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Today is a sunny day and I will get some ice cream."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to embed.
normalize 	boolean 	
prompt_name 	string 	The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the sentence-transformers configuration prompts dictionary. For example if prompt_name is “query” and the prompts is {“query”: “query: ”, …}, then the sentence “What is the capital of France?” will be encoded as “query: What is the capital of France?” because the prompt text will be prepended before any text to encode.
truncate 	boolean 	
truncation_direction 	enum 	Possible values: Left, Right.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	array[] 	Output is an array of arrays.
< > Update on GitHub

Chat Completion
←Chat Completion
Fill Mask→

Fill-mask

Mask filling is the task of predicting the right word (token to be precise) in the middle of a sequence.

For more details about the fill-mask task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google-bert/bert-base-uncased: The famous BERT model.
    FacebookAI/xlm-roberta-base: A multilingual model trained on 100 languages.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google-bert/bert-base-uncased",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "The answer to the universe is [MASK]."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text with masked tokens
parameters 	object 	
        top_k 	integer 	When passed, overrides the number of predictions to return.
        targets 	string[] 	When passed, the model will limit the scores to the passed targets instead of looking up in the whole vocabulary. If the provided targets are not in the model vocab, they will be tokenized and the first resulting token will be used (with a warning, and that might be slower).

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        sequence 	string 	The corresponding input with the mask token prediction.
        score 	number 	The corresponding probability
        token 	integer 	The predicted token id (to replace the masked one).
        token_str 	string 	The predicted token (to replace the masked one).
< > Update on GitHub

Feature Extraction
←Feature Extraction
Image Classification→

Image Classification

Image classification is the task of assigning a label or class to an entire image. Images are expected to have only one class for each image.

For more details about the image-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/vit-base-patch16-224: A strong image classification model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/vit-base-patch16-224",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Fill-mask
←Fill Mask
Image Segmentation→

Image Segmentation

Image Segmentation divides an image into segments where each pixel in the image is mapped to an object.

For more details about the image-segmentation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    openmmlab/upernet-convnext-small: Solid semantic segmentation model trained on ADE20k.
    facebook/mask2former-swin-large-coco-panoptic: Panoptic segmentation model trained on the COCO (common objects) dataset.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/openmmlab/upernet-convnext-small",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        mask_threshold 	number 	Threshold to use when turning the predicted masks into binary values.
        overlap_mask_area_threshold 	number 	Mask overlap threshold to eliminate small, disconnected segments.
        subtask 	enum 	Possible values: instance, panoptic, semantic.
        threshold 	number 	Probability threshold to filter out predicted masks.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	A predicted mask / segment
        label 	string 	The label of the predicted segment.
        mask 	string 	The corresponding mask as a black-and-white image (base64-encoded).
        score 	number 	The score or confidence degree the model has.
< > Update on GitHub

Image Classification
←Image Classification
Image to Image→

Image to Image

Image-to-image is the task of transforming a source image to match the characteristics of a target image or a target image domain.

Example applications:

    Transferring the style of an image to another image
    Colorizing a black and white image
    Increasing the resolution of an image

For more details about the image-to-image task, check out its dedicated page! You will find examples and related materials.
Recommended models

    timbrooks/instruct-pix2pix: A model that takes an image and an instruction to edit the image.

Explore all available models and find the one that suits you best here.
Using the API

No snippet available for this task.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        guidance_scale 	number 	For diffusion models. A higher guidance scale value encourages the model to generate images closely linked to the text prompt at the expense of lower image quality.
        negative_prompt 	string[] 	One or several prompt to guide what NOT to include in image generation.
        num_inference_steps 	integer 	For diffusion models. The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.
        target_size 	object 	The size in pixel of the output image.
                width* 	integer 	
                height* 	integer 	

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
image 	unknown 	The output image returned as raw bytes in the payload.
< > Update on GitHub

Image Segmentation
←Image Segmentation
Image-Text to Text→Image-Text to Text

Image-text-to-text models take in an image and text prompt and output text. These models are also called vision-language models, or VLMs. The difference from image-to-text models is that these models take an additional text input, not restricting the model to certain use cases like image captioning, and may also be trained to accept a conversation as input.

For more details about the image-text-to-text task, check out its dedicated page! You will find examples and related materials.
Recommended models

    meta-llama/Llama-3.2-11B-Vision-Instruct: Powerful vision language model with great visual understanding and reasoning capabilities.
    Qwen/Qwen2-VL-7B-Instruct: Strong image-text-to-text model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/meta-llama/Llama-3.2-11B-Vision-Instruct",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Can you please let us know more details about your "}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification

For the API specification of conversational image-text-to-text models, please refer to the Chat Completion API documentation.
< > Update on GitHub

Image-Text to Text
←Image to Image
Object Detection→Object detection

Object Detection models allow users to identify objects of certain defined classes. These models receive an image as input and output the images with bounding boxes and labels on detected objects.

For more details about the object-detection task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/detr-resnet-50: Solid object detection model pre-trained on the COCO 2017 dataset.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/detr-resnet-50",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        threshold 	number 	The probability necessary to make a prediction.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted label for the bounding box.
        score 	number 	The associated score / probability.
        box 	object 	
                xmin 	integer 	The x-coordinate of the top-left corner of the bounding box.
                xmax 	integer 	The x-coordinate of the bottom-right corner of the bounding box.
                ymin 	integer 	The y-coordinate of the top-left corner of the bounding box.
                ymax 	integer 	The y-coordinate of the bottom-right corner of the bounding box.
< > Update on GitHub

Image-Text to Text
←Image-Text to Text
Question Answering→

Question Answering

Question Answering models can retrieve the answer to a question from a given text, which is useful for searching for an answer in a document.

For more details about the question-answering task, check out its dedicated page! You will find examples and related materials.
Recommended models

    deepset/roberta-base-squad2: A robust baseline model for most question answering domains.
    distilbert/distilbert-base-cased-distilled-squad: Small yet robust model that can answer questions.
    google/tapas-base-finetuned-wtq: A special model that can answer questions from tables.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/deepset/roberta-base-squad2",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": {
	"question": "What is my name?",
	"context": "My name is Clara and I live in Berkeley."
}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	object 	One (context, question) pair to answer
        context* 	string 	The context to be used for answering the question
        question* 	string 	The question to be answered
parameters 	object 	
        top_k 	integer 	The number of answers to return (will be chosen by order of likelihood). Note that we return less than topk answers if there are not enough options available within the context.
        doc_stride 	integer 	If the context is too long to fit with the question for the model, it will be split in several chunks with some overlap. This argument controls the size of that overlap.
        max_answer_len 	integer 	The maximum length of predicted answers (e.g., only answers with a shorter length are considered).
        max_seq_len 	integer 	The maximum length of the total sentence (context + question) in tokens of each chunk passed to the model. The context will be split in several chunks (using docStride as overlap) if needed.
        max_question_len 	integer 	The maximum length of the question after tokenization. It will be truncated if needed.
        handle_impossible_answer 	boolean 	Whether to accept impossible as an answer.
        align_to_words 	boolean 	Attempts to align the answer to real words. Improves quality on space separated languages. Might hurt on non-space-separated languages (like Japanese or Chinese)

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        answer 	string 	The answer to the question.
        score 	number 	The probability associated to the answer.
        start 	integer 	The character position in the input where the answer begins.
        end 	integer 	The character position in the input where the answer ends.
< > Update on GitHub

Object detection
←Object Detection
Summarization→

Summarization

Summarization is the task of producing a shorter version of a document while preserving its important information. Some models can extract text from the original input, while other models can generate entirely new text.

For more details about the summarization task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/bart-large-cnn: A strong summarization model trained on English news articles. Excels at generating factual summaries.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/bart-large-cnn",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "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. It was the first structure to reach a height of 300 metres. Due to the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the Chrysler Building by 5.2 metres (17 ft). Excluding transmitters, the Eiffel Tower is the second tallest free-standing structure in France after the Millau Viaduct."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text to summarize.
parameters 	object 	
        clean_up_tokenization_spaces 	boolean 	Whether to clean up the potential extra spaces in the text output.
        truncation 	enum 	Possible values: do_not_truncate, longest_first, only_first, only_second.
        generate_parameters 	object 	Additional parametrization of the text generation algorithm.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
summary_text 	string 	The summarized text.
< > Update on GitHub

Question Answering
←Question Answering
Table Question Answering→

Table Question Answering

Table Question Answering (Table QA) is the answering a question about an information on a given table.

For more details about the table-question-answering task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/tapas-base-finetuned-wtq: A robust table question answering model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/tapas-base-finetuned-wtq",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": {
	"query": "How many stars does the transformers repository have?",
	"table": {
		"Repository": ["Transformers", "Datasets", "Tokenizers"],
		"Stars": ["36542", "4512", "3934"],
		"Contributors": ["651", "77", "34"],
		"Programming language": [
			"Python",
			"Python",
			"Rust, Python and NodeJS"
		]
	}
}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	object 	One (table, question) pair to answer
        table* 	object 	The table to serve as context for the questions
        question* 	string 	The question to be answered about the table
parameters 	object 	
        padding 	enum 	Possible values: do_not_pad, longest, max_length.
        sequential 	boolean 	Whether to do inference sequentially or as a batch. Batching is faster, but models like SQA require the inference to be done sequentially to extract relations within sequences, given their conversational nature.
        truncation 	boolean 	Activates and controls truncation.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        answer 	string 	The answer of the question given the table. If there is an aggregator, the answer will be preceded by AGGREGATOR >.
        coordinates 	array[] 	Coordinates of the cells of the answers.
        cells 	string[] 	List of strings made up of the answer cell values.
        aggregator 	string 	If the model has an aggregator, this returns the aggregator.
< > Update on GitHub

Summarization
←Summarization
Text Classification→Text Classification

Text Classification is the task of assigning a label or class to a given text. Some use cases are sentiment analysis, natural language inference, and assessing grammatical correctness.

For more details about the text-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    distilbert/distilbert-base-uncased-finetuned-sst-2-english: A robust model trained for sentiment analysis.
    ProsusAI/finbert: A sentiment analysis model specialized in financial sentiment.
    cardiffnlp/twitter-roberta-base-sentiment-latest: A sentiment analysis model specialized in analyzing tweets.
    papluca/xlm-roberta-base-language-detection: A model that can classify languages.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/distilbert/distilbert-base-uncased-finetuned-sst-2-english",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "I like you. I love you"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to classify
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Table Question Answering
←Table Question Answering
Text Generation→

Text Generation

Generate text based on a prompt.

If you are interested in a Chat Completion task, which generates a response based on a list of messages, check out the chat-completion task.

For more details about the text-generation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/gemma-2-2b-it: A text-generation model trained to follow instructions.
    meta-llama/Meta-Llama-3.1-8B-Instruct: Very powerful text generation model trained to follow instructions.
    microsoft/Phi-3-mini-4k-instruct: Small yet powerful text generation model.
    Qwen/Qwen2.5-7B-Instruct: Strong text generation model to follow instructions.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/gemma-2-2b-it",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Can you please let us know more details about your "}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	
parameters 	object 	
        adapter_id 	string 	Lora adapter id
        best_of 	integer 	Generate best_of sequences and return the one if the highest token logprobs.
        decoder_input_details 	boolean 	Whether to return decoder input token logprobs and ids.
        details 	boolean 	Whether to return generation details.
        do_sample 	boolean 	Activate logits sampling.
        frequency_penalty 	number 	The parameter for frequency penalty. 1.0 means no penalty Penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.
        grammar 	unknown 	One of the following:
                 (#1) 	object 	
                        type* 	enum 	Possible values: json.
                        value* 	unknown 	A string that represents a JSON Schema. JSON Schema is a declarative language that allows to annotate JSON documents with types and descriptions.
                 (#2) 	object 	
                        type* 	enum 	Possible values: regex.
                        value* 	string 	
        max_new_tokens 	integer 	Maximum number of tokens to generate.
        repetition_penalty 	number 	The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details.
        return_full_text 	boolean 	Whether to prepend the prompt to the generated text
        seed 	integer 	Random sampling seed.
        stop 	string[] 	Stop generating tokens if a member of stop is generated.
        temperature 	number 	The value used to module the logits distribution.
        top_k 	integer 	The number of highest probability vocabulary tokens to keep for top-k-filtering.
        top_n_tokens 	integer 	The number of highest probability vocabulary tokens to keep for top-n-filtering.
        top_p 	number 	Top-p value for nucleus sampling.
        truncate 	integer 	Truncate inputs tokens to the given size.
        typical_p 	number 	Typical Decoding mass See Typical Decoding for Natural Language Generation for more information.
        watermark 	boolean 	Watermarking with A Watermark for Large Language Models.
stream 	boolean 	

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
details 	object 	
        best_of_sequences 	object[] 	
                finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
                generated_text 	string 	
                generated_tokens 	integer 	
                prefill 	object[] 	
                        id 	integer 	
                        logprob 	number 	
                        text 	string 	
                seed 	integer 	
                tokens 	object[] 	
                        id 	integer 	
                        logprob 	number 	
                        special 	boolean 	
                        text 	string 	
                top_tokens 	array[] 	
                        id 	integer 	
                        logprob 	number 	
                        special 	boolean 	
                        text 	string 	
        finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
        generated_tokens 	integer 	
        prefill 	object[] 	
                id 	integer 	
                logprob 	number 	
                text 	string 	
        seed 	integer 	
        tokens 	object[] 	
                id 	integer 	
                logprob 	number 	
                special 	boolean 	
                text 	string 	
        top_tokens 	array[] 	
                id 	integer 	
                logprob 	number 	
                special 	boolean 	
                text 	string 	
generated_text 	string 	

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
Body 		
details 	object 	
        finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
        generated_tokens 	integer 	
        input_length 	integer 	
        seed 	integer 	
generated_text 	string 	
index 	integer 	
token 	object 	
        id 	integer 	
        logprob 	number 	
        special 	boolean 	
        text 	string 	
top_tokens 	object[] 	
        id 	integer 	
        logprob 	number 	
        special 	boolean 	
        text 	string 	
< > Update on GitHub

Text Classification
←Text Classification
Text to Image→

Text to Image

Generate an image based on a given text prompt.

For more details about the text-to-image task, check out its dedicated page! You will find examples and related materials.
Recommended models

    black-forest-labs/FLUX.1-dev: One of the most powerful image generation models that can generate realistic outputs.
    stabilityai/stable-diffusion-3-medium-diffusers: A powerful text-to-image model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/black-forest-labs/FLUX.1-dev",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.blob();
	return result;
}
query({"inputs": "Astronaut riding a horse"}).then((response) => {
	// Use image
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text data (sometimes called “prompt”)
parameters 	object 	
        guidance_scale 	number 	A higher guidance scale value encourages the model to generate images closely linked to the text prompt, but values too high may cause saturation and other artifacts.
        negative_prompt 	string[] 	One or several prompt to guide what NOT to include in image generation.
        num_inference_steps 	integer 	The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.
        target_size 	object 	The size in pixel of the output image
                width* 	integer 	
                height* 	integer 	
        scheduler 	string 	Override the scheduler with a compatible one.
        seed 	integer 	Seed for the random number generator.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
image 	unknown 	The generated image returned as raw bytes in the payload.
< > Update on GitHub

Text Generation
←Text Generation
Token Classification→

Token Classification

Token classification is a task in which a label is assigned to some tokens in a text. Some popular token classification subtasks are Named Entity Recognition (NER) and Part-of-Speech (PoS) tagging.

For more details about the token-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    dslim/bert-base-NER: A robust performance model to identify people, locations, organizations and names of miscellaneous entities.
    FacebookAI/xlm-roberta-large-finetuned-conll03-english: A strong model to identify people, locations, organizations and names in multiple languages.
    blaze999/Medical-NER: A token classification model specialized on medical entity recognition.
    flair/ner-english: Flair models are typically the state of the art in named entity recognition tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/dslim/bert-base-NER",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "My name is Sarah Jessica Parker but you can call me Jessica"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text data
parameters 	object 	
        ignore_labels 	string[] 	A list of labels to ignore
        stride 	integer 	The number of overlapping tokens between chunks when splitting the input text.
        aggregation_strategy 	string 	One of the following:
                 (#1) 	’none’ 	Do not aggregate tokens
                 (#2) 	’simple’ 	Group consecutive tokens with the same label in a single entity.
                 (#3) 	’first’ 	Similar to “simple”, also preserves word integrity (use the label predicted for the first token in a word).
                 (#4) 	’average’ 	Similar to “simple”, also preserves word integrity (uses the label with the highest score, averaged across the word’s tokens).
                 (#5) 	’max’ 	Similar to “simple”, also preserves word integrity (uses the label with the highest score across the word’s tokens).

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
(array) 	object[] 	Output is an array of objects.
        entity_group 	string 	The predicted label for a group of one or more tokens
        entity 	string 	The predicted label for a single token
        score 	number 	The associated score / probability
        word 	string 	The corresponding text
        start 	integer 	The character position in the input where this group begins.
        end 	integer 	The character position in the input where this group ends.

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
< > Update on GitHub

Token Classification
←Text to Image
Translation→

Translation

Translation is the task of converting text from one language to another.

For more details about the translation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google-t5/t5-base: A general-purpose Transformer that can be used to translate from English to German, French, or Romanian.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google-t5/t5-base",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Меня зовут Вольфганг и я живу в Берлине"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to translate.
parameters 	object 	
        src_lang 	string 	The source language of the text. Required for models that can translate from multiple languages.
        tgt_lang 	string 	Target language to translate to. Required for models that can translate to multiple languages.
        clean_up_tokenization_spaces 	boolean 	Whether to clean up the potential extra spaces in the text output.
        truncation 	enum 	Possible values: do_not_truncate, longest_first, only_first, only_second.
        generate_parameters 	object 	Additional parametrization of the text generation algorithm.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
translation_text 	string 	The translated text.
< > Update on GitHub

Token Classification
←Token Classification
Zero Shot Classification→Zero-Shot Classification

Zero-shot text classification 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. The model has not been necessarily trained on the labels you provide, but it can still predict the correct label.

For more details about the zero-shot-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/bart-large-mnli: Powerful zero-shot text classification model.
    MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7: Powerful zero-shot multilingual text classification model that can accomplish multiple tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/bart-large-mnli",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!", "parameters": {"candidate_labels": ["refund", "legal", "faq"]}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to classify
parameters* 	object 	
        candidate_labels* 	string[] 	The set of possible class labels to classify the text into.
        hypothesis_template 	string 	The sentence used in conjunction with candidate_labels to attempt the text classification by replacing the placeholder with the candidate labels.
        multi_label 	boolean 	Whether multiple candidate labels can be true. If false, the scores are normalized such that the sum of the label likelihoods for each sequence is 1. If true, the labels are considered independent and probabilities are normalized for each candidate.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Zero-Shot Classification
←Translation
Getting Started→

""".

you need to learn all this docu to generate:



"""

Serverless Inference API

Instant Access to thousands of ML Models for Fast Prototyping

Explore the most popular models for text, image, speech, and more — all with a simple API request. Build, test, and experiment without worrying about infrastructure or setup.
Why use the Inference API?

The Serverless Inference API offers a fast and free way to explore thousands of models for a variety of tasks. Whether you’re prototyping a new application or experimenting with ML capabilities, this API gives you instant access to high-performing models across multiple domains:

    Text Generation: Including large language models and tool-calling prompts, generate and experiment with high-quality responses.
    Image Generation: Easily create customized images, including LoRAs for your own styles.
    Document Embeddings: Build search and retrieval systems with SOTA embeddings.
    Classical AI Tasks: Ready-to-use models for text classification, image classification, speech recognition, and more.

⚡ Fast and Free to Get Started: The Inference API is free with higher rate limits for PRO users. For production needs, explore Inference Endpoints for dedicated resources, autoscaling, advanced security features, and more.
Key Benefits

    🚀 Instant Prototyping: Access powerful models without setup.
    🎯 Diverse Use Cases: One API for text, image, and beyond.
    🔧 Developer-Friendly: Simple requests, fast responses.

Main Features

    Leverage over 800,000+ models from different open-source libraries (transformers, sentence transformers, adapter transformers, diffusers, timm, etc.).
    Use models for a variety of tasks, including text generation, image generation, document embeddings, NER, summarization, image classification, and more.
    Accelerate your prototyping by using GPU-powered models.
    Run very large models that are challenging to deploy in production.
    Production-grade platform without the hassle: built-in automatic scaling, load balancing and caching.

Contents

The documentation is organized into two sections:

    Getting Started Learn the basics of how to use the Inference API.
    API Reference Dive into task-specific settings and parameters.Getting Started

The Serverless Inference API allows you to easily do inference on a wide range of models and tasks. You can do requests with your favorite tools (Python, cURL, etc). We also provide a Python SDK (huggingface_hub) to make it even easier.

We’ll do a minimal example using a sentiment classification model. Please visit task-specific parameters and further documentation in our API Reference.
Getting a Token

Using the Serverless Inference API requires passing a user token in the request headers. You can get a token by signing up on the Hugging Face website and then going to the tokens page. We recommend creating a fine-grained token with the scope to Make calls to the serverless Inference API.

For more details about user tokens, check out this guide.
cURL

curl 'https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest' \
-H "Authorization: Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H 'Content-Type: application/json' \
-d '{"inputs": "Today is a great day"}'

Python

You can use the requests library to make a request to the Inference API.

import requests

API_URL = "https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest"
headers = {"Authorization": "Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
payload = {
    "inputs": "Today is a great day",
}

response = requests.post(API_URL, headers=headers, json=payload)
response.json()

Hugging Face also provides a InferenceClient that handles inference for you. Make sure to install it with pip install huggingface_hub first.

from huggingface_hub import InferenceClient

client = InferenceClient(
    "cardiffnlp/twitter-roberta-base-sentiment-latest",
    token="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

client.text_classification("Today is a great day")

JavaScript

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/cardiffnlp/twitter-roberta-base-sentiment-latest",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,
                "Content-Type": "application/json",
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({inputs: "Today is a great day"}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

Hugging Face also provides a HfInference client that handles inference. Make sure to install it with npm install @huggingface/inference first.

import { HfInference } from "@huggingface/inference";

const inference = new HfInference("hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx");

const result = await inference.textClassification({
    model: "cardiffnlp/twitter-roberta-base-sentiment-latest",
    inputs: "Today is a great day",
});

console.log(result);

Next Steps

Now that you know the basics, you can explore the API Reference to learn more about task-specific settings and parameters.Supported Models

Given the fast-paced nature of the open ML ecosystem, the Inference API exposes models that have large community interest and are in active use (based on recent likes, downloads, and usage). Because of this, deployed models can be swapped without prior notice. The Hugging Face stack aims to keep all the latest popular models warm and ready to use.

You can find:

    Warm models: models ready to be used.
    Cold models: models that are not loaded but can be used.
    Frozen models: models that currently can’t be run with the API.

What do I get with a PRO subscription?

In addition to thousands of public models available in the Hub, PRO and Enterprise users get higher rate limits and free access to the following models:
Model 	Size 	Supported Context Length 	Use
Meta Llama 3.1 Instruct 	8B, 70B 	70B: 32k tokens / 8B: 8k tokens 	High quality multilingual chat model with large context length
Meta Llama 3 Instruct 	8B, 70B 	8k tokens 	One of the best chat models
Meta Llama Guard 3 	8B 	4k tokens 	
Llama 2 Chat 	7B, 13B, 70B 	4k tokens 	One of the best conversational models
DeepSeek Coder v2 	236B 	16k tokens 	A model with coding capabilities.
Bark 	0.9B 	- 	Text to audio generation

This list is not exhaustive and might be updated in the future.
Running Private Models

The free Serverless API is designed to run popular public models. If you have a private model, you can use Inference Endpoints to deploy it.Rate Limits

The Inference API has rate limits based on the number of requests. These rate limits are subject to change in the future to be compute-based or token-based.

Serverless API is not meant to be used for heavy production applications. If you need higher rate limits, consider Inference Endpoints to have dedicated resources.

You need to be authenticated (passing a token or through your browser) to use the Inference API.
User Tier 	Rate Limit
Signed-up Users 	1,000 requests per day
PRO and Enterprise Users 	20,000 requests per day
< > Update on GitHub

Supported Models
←Supported Models
SecuritySecurity & Compliance

The Inference API is not designed for heavy production requirements. For production needs, explore Inference Endpoints for dedicated resources, autoscaling, advanced security features, and more.
Data Security/Privacy

Hugging Face does not store any user data for training purposes. Tokens sent to the API might be stored in a short-term (few minutes) cache mechanism to speed-up repeated requests. Logs are stored for debugging for up to 30 days. Any additional data in terms of user data or tokens are not stored.

Serverless Inference API use TLS/SSL to encrypt the data in transit.
Hub Security

The Hugging Face Hub, which Serverless Inference API is part, is SOC2 Type 2 certified. For more on Hub security: https://huggingface.co/docs/hub/security
< > Update on GitHub

Rate Limits
←Rate Limits
Parameters→Parameters
Additional Options
Caching

There is a cache layer on the inference API to speed up requests when the inputs are exactly the same. Many models, such as classifiers and embedding models, can use those results as is if they are deterministic, meaning the results will be the same. However, if you use a nondeterministic model, you can disable the cache mechanism from being used, resulting in a real new query.

To do this, you can add x-use-cache:false to the request headers. For example

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/MODEL_ID",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_***`,
                "Content-Type": "application/json",
+               "x-use-cache": "false"
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({
    inputs: "Can you please let us know more details about your "
}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

Wait for the model

When a model is warm, it is ready to be used and you will get a response relatively quickly. However, some models are cold and need to be loaded before they can be used. In that case, you will get a 503 error. Rather than doing many requests until it’s loaded, you can wait for the model to be loaded by adding x-wait-for-model:true to the request headers. We suggest to only use this flag to wait for the model to be loaded when you are sure that the model is cold. That means, first try the request without this flag and only if you get a 503 error, try again with this flag.

import fetch from "node-fetch";

async function query(data) {
    const response = await fetch(
        "https://api-inference.huggingface.co/models/MODEL_ID",
        {
            method: "POST",
            headers: {
                Authorization: `Bearer hf_***`,
                "Content-Type": "application/json",
+               "x-wait-for-model": "true"
            },
            body: JSON.stringify(data),
        }
    );
    const result = await response.json();
    return result;
}

query({
    inputs: "Can you please let us know more details about your "
}).then((response) => {
    console.log(JSON.stringify(response, null, 2));
});

< > Update on GitHub

Parameters
←Security
Audio ClassificationAudio Classification

Audio classification is the task of assigning a label or class to a given audio.

Example applications:

    Recognizing which command a user is giving
    Identifying a speaker
    Detecting the genre of a song

For more details about the audio-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition: An emotion recognition model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/ehcalabres/wav2vec2-lg-xlsr-en-speech-emotion-recognition",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("sample1.flac").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input audio data as a base64-encoded string. If no parameters are provided, you can also provide the audio data as a raw bytes payload.
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Audio Classification
←Parameters
Automatic Speech RecognitionAutomatic Speech Recognition

Automatic Speech Recognition (ASR), also known as Speech to Text (STT), is the task of transcribing a given audio to text.

Example applications:

    Transcribing a podcast
    Building a voice assistant
    Generating subtitles for a video

For more details about the automatic-speech-recognition task, check out its dedicated page! You will find examples and related materials.
Recommended models

    openai/whisper-large-v3: A powerful ASR model by OpenAI.
    nvidia/canary-1b: A powerful multilingual ASR and Speech Translation model by Nvidia.
    pyannote/speaker-diarization-3.1: Powerful speaker diarization model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/openai/whisper-large-v3",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("sample1.flac").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input audio data as a base64-encoded string. If no parameters are provided, you can also provide the audio data as a raw bytes payload.
parameters 	object 	
        return_timestamps 	boolean 	Whether to output corresponding timestamps with the generated text
        generation_parameters 	object 	
                temperature 	number 	The value used to modulate the next token probabilities.
                top_k 	integer 	The number of highest probability vocabulary tokens to keep for top-k-filtering.
                top_p 	number 	If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation.
                typical_p 	number 	Local typicality measures how similar the conditional probability of predicting a target token next is to the expected conditional probability of predicting a random token next, given the partial text already generated. If set to float < 1, the smallest set of the most locally typical tokens with probabilities that add up to typical_p or higher are kept for generation. See this paper for more details.
                epsilon_cutoff 	number 	If set to float strictly between 0 and 1, only tokens with a conditional probability greater than epsilon_cutoff will be sampled. In the paper, suggested values range from 3e-4 to 9e-4, depending on the size of the model. See Truncation Sampling as Language Model Desmoothing for more details.
                eta_cutoff 	number 	Eta sampling is a hybrid of locally typical sampling and epsilon sampling. If set to float strictly between 0 and 1, a token is only considered if it is greater than either eta_cutoff or sqrt(eta_cutoff) * exp(-entropy(softmax(next_token_logits))). The latter term is intuitively the expected next token probability, scaled by sqrt(eta_cutoff). In the paper, suggested values range from 3e-4 to 2e-3, depending on the size of the model. See Truncation Sampling as Language Model Desmoothing for more details.
                max_length 	integer 	The maximum length (in tokens) of the generated text, including the input.
                max_new_tokens 	integer 	The maximum number of tokens to generate. Takes precedence over max_length.
                min_length 	integer 	The minimum length (in tokens) of the generated text, including the input.
                min_new_tokens 	integer 	The minimum number of tokens to generate. Takes precedence over min_length.
                do_sample 	boolean 	Whether to use sampling instead of greedy decoding when generating new tokens.
                early_stopping 	enum 	Possible values: never, true, false.
                num_beams 	integer 	Number of beams to use for beam search.
                num_beam_groups 	integer 	Number of groups to divide num_beams into in order to ensure diversity among different groups of beams. See this paper for more details.
                penalty_alpha 	number 	The value balances the model confidence and the degeneration penalty in contrastive search decoding.
                use_cache 	boolean 	Whether the model should use the past last key/values attentions to speed up decoding

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
text 	string 	The recognized text.
chunks 	object[] 	When returnTimestamps is enabled, chunks contains a list of audio chunks identified by the model.
        text 	string 	A chunk of text identified by the model
        timestamps 	number[] 	The start and end timestamps corresponding with the text
< > Update on GitHub

Audio Classification
←Audio Classification
Chat Completion→Chat Completion

Generate a response given a list of messages in a conversational context, supporting both conversational Language Models (LLMs) and conversational Vision-Language Models (VLMs). This is a subtask of text-generation and image-text-to-text.
Recommended models
Conversational Large Language Models (LLMs)

    google/gemma-2-2b-it: A text-generation model trained to follow instructions.
    meta-llama/Meta-Llama-3.1-8B-Instruct: Very powerful text generation model trained to follow instructions.
    microsoft/Phi-3-mini-4k-instruct: Small yet powerful text generation model.
    Qwen/Qwen2.5-7B-Instruct: Strong text generation model to follow instructions.

Conversational Vision-Language Models (VLMs)

    meta-llama/Llama-3.2-11B-Vision-Instruct: Powerful vision language model with great visual understanding and reasoning capabilities.
    Qwen/Qwen2-VL-7B-Instruct: Strong image-text-to-text model.

API Playground

For Chat Completion models, we provide an interactive UI Playground for easier testing:

    Quickly iterate on your prompts from the UI.
    Set and override system, assistant and user messages.
    Browse and select models currently available on the Inference API.
    Compare the output of two models side-by-side.
    Adjust requests parameters from the UI.
    Easily switch between UI view and code snippets.

Access the Inference UI Playground and start exploring: https://huggingface.co/playground
Using the API

The API supports:

    Using the chat completion API compatible with the OpenAI SDK.
    Using grammars, constraints, and tools.
    Streaming the output

Code snippet example for conversational LLMs

Using huggingface.js:

import { HfInference } from "@huggingface/inference";

const client = new HfInference("hf_***");

let out = "";

const stream = client.chatCompletionStream({
	model: "google/gemma-2-2b-it",
	messages: [
		{
			role: "user",
			content: "What is the capital of France?"
		}
	],
	max_tokens: 500
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

Using openai:

import { OpenAI } from "openai";

const client = new OpenAI({
	baseURL: "https://api-inference.huggingface.co/v1/",
    apiKey: "hf_***"
});

let out = "";

const stream = await client.chat.completions.create({
	model: "google/gemma-2-2b-it",
	messages: [
		{
			role: "user",
			content: "What is the capital of France?"
		}
	],
	max_tokens: 500,
	stream: true,
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

To use the JavaScript client, see huggingface.js’s package reference.
Code snippet example for conversational VLMs

Using huggingface.js:

import { HfInference } from "@huggingface/inference";

const client = new HfInference("hf_***");

let out = "";

const stream = client.chatCompletionStream({
	model: "meta-llama/Llama-3.2-11B-Vision-Instruct",
	messages: [
		{
			role: "user",
			content: [
				{
					type: "text",
					text: "Describe this image in one sentence."
				},
				{
					type: "image_url",
					image_url: {
						url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
					}
				}
			]
		}
	],
	max_tokens: 500
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

Using openai:

import { OpenAI } from "openai";

const client = new OpenAI({
	baseURL: "https://api-inference.huggingface.co/v1/",
    apiKey: "hf_***"
});

let out = "";

const stream = await client.chat.completions.create({
	model: "meta-llama/Llama-3.2-11B-Vision-Instruct",
	messages: [
		{
			role: "user",
			content: [
				{
					type: "text",
					text: "Describe this image in one sentence."
				},
				{
					type: "image_url",
					image_url: {
						url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
					}
				}
			]
		}
	],
	max_tokens: 500,
	stream: true,
});

for await (const chunk of stream) {
	if (chunk.choices && chunk.choices.length > 0) {
		const newContent = chunk.choices[0].delta.content;
		out += newContent;
		console.log(newContent);
	}  
}

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
frequency_penalty 	number 	Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.
logprobs 	boolean 	Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message.
max_tokens 	integer 	The maximum number of tokens that can be generated in the chat completion.
messages* 	object[] 	A list of messages comprising the conversation so far.
        content* 	unknown 	One of the following:
                 (#1) 	string 	
                 (#2) 	object[] 	
                         (#1) 	object 	
                                text* 	string 	
                                type* 	enum 	Possible values: text.
                         (#2) 	object 	
                                image_url* 	object 	
                                        url* 	string 	
                                type* 	enum 	Possible values: image_url.
        name 	string 	
        role* 	string 	
presence_penalty 	number 	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model’s likelihood to talk about new topics
response_format 	unknown 	One of the following:
         (#1) 	object 	
                type* 	enum 	Possible values: json.
                value* 	unknown 	A string that represents a JSON Schema. JSON Schema is a declarative language that allows to annotate JSON documents with types and descriptions.
         (#2) 	object 	
                type* 	enum 	Possible values: regex.
                value* 	string 	
seed 	integer 	
stop 	string[] 	Up to 4 sequences where the API will stop generating further tokens.
stream 	boolean 	
stream_options 	object 	
        include_usage* 	boolean 	If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array. All other chunks will also include a usage field, but with a null value.
temperature 	number 	What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.
tool_choice 	unknown 	One of the following:
         (#1) 	enum 	Possible values: auto.
         (#2) 	enum 	Possible values: none.
         (#3) 	enum 	Possible values: required.
         (#4) 	object 	
                function* 	object 	
                        name* 	string 	
tool_prompt 	string 	A prompt to be appended before the tools
tools 	object[] 	A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
        function* 	object 	
                arguments* 	unknown 	
                description 	string 	
                name* 	string 	
        type* 	string 	
top_logprobs 	integer 	An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.
top_p 	number 	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
choices 	object[] 	
        finish_reason 	string 	
        index 	integer 	
        logprobs 	object 	
                content 	object[] 	
                        logprob 	number 	
                        token 	string 	
                        top_logprobs 	object[] 	
                                logprob 	number 	
                                token 	string 	
        message 	unknown 	One of the following:
                 (#1) 	object 	
                        content 	string 	
                        role 	string 	
                 (#2) 	object 	
                        role 	string 	
                        tool_calls 	object[] 	
                                function 	object 	
                                        arguments 	unknown 	
                                        description 	string 	
                                        name 	string 	
                                id 	string 	
                                type 	string 	
created 	integer 	
id 	string 	
model 	string 	
system_fingerprint 	string 	
usage 	object 	
        completion_tokens 	integer 	
        prompt_tokens 	integer 	
        total_tokens 	integer 	

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
Body 		
choices 	object[] 	
        delta 	unknown 	One of the following:
                 (#1) 	object 	
                        content 	string 	
                        role 	string 	
                 (#2) 	object 	
                        role 	string 	
                        tool_calls 	object 	
                                function 	object 	
                                        arguments 	string 	
                                        name 	string 	
                                id 	string 	
                                index 	integer 	
                                type 	string 	
        finish_reason 	string 	
        index 	integer 	
        logprobs 	object 	
                content 	object[] 	
                        logprob 	number 	
                        token 	string 	
                        top_logprobs 	object[] 	
                                logprob 	number 	
                                token 	string 	
created 	integer 	
id 	string 	
model 	string 	
system_fingerprint 	string 	
usage 	object 	
        completion_tokens 	integer 	
        prompt_tokens 	integer 	
        total_tokens 	integer 	
< > Update on GitHub

Chat Completion
←Automatic Speech Recognition
Feature Extraction→Feature Extraction

Feature extraction is the task of converting a text into a vector (often called “embedding”).

Example applications:

    Retrieving the most relevant documents for a query (for RAG applications).
    Reranking a list of documents based on their similarity to a query.
    Calculating the similarity between two sentences.

For more details about the feature-extraction task, check out its dedicated page! You will find examples and related materials.
Recommended models

    thenlper/gte-large: A powerful feature extraction model for natural language processing tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/thenlper/gte-large",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Today is a sunny day and I will get some ice cream."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to embed.
normalize 	boolean 	
prompt_name 	string 	The name of the prompt that should be used by for encoding. If not set, no prompt will be applied. Must be a key in the sentence-transformers configuration prompts dictionary. For example if prompt_name is “query” and the prompts is {“query”: “query: ”, …}, then the sentence “What is the capital of France?” will be encoded as “query: What is the capital of France?” because the prompt text will be prepended before any text to encode.
truncate 	boolean 	
truncation_direction 	enum 	Possible values: Left, Right.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	array[] 	Output is an array of arrays.
< > Update on GitHub

Chat Completion
←Chat Completion
Fill Mask→

Fill-mask

Mask filling is the task of predicting the right word (token to be precise) in the middle of a sequence.

For more details about the fill-mask task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google-bert/bert-base-uncased: The famous BERT model.
    FacebookAI/xlm-roberta-base: A multilingual model trained on 100 languages.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google-bert/bert-base-uncased",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "The answer to the universe is [MASK]."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text with masked tokens
parameters 	object 	
        top_k 	integer 	When passed, overrides the number of predictions to return.
        targets 	string[] 	When passed, the model will limit the scores to the passed targets instead of looking up in the whole vocabulary. If the provided targets are not in the model vocab, they will be tokenized and the first resulting token will be used (with a warning, and that might be slower).

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        sequence 	string 	The corresponding input with the mask token prediction.
        score 	number 	The corresponding probability
        token 	integer 	The predicted token id (to replace the masked one).
        token_str 	string 	The predicted token (to replace the masked one).
< > Update on GitHub

Feature Extraction
←Feature Extraction
Image Classification→

Image Classification

Image classification is the task of assigning a label or class to an entire image. Images are expected to have only one class for each image.

For more details about the image-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/vit-base-patch16-224: A strong image classification model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/vit-base-patch16-224",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Fill-mask
←Fill Mask
Image Segmentation→

Image Segmentation

Image Segmentation divides an image into segments where each pixel in the image is mapped to an object.

For more details about the image-segmentation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    openmmlab/upernet-convnext-small: Solid semantic segmentation model trained on ADE20k.
    facebook/mask2former-swin-large-coco-panoptic: Panoptic segmentation model trained on the COCO (common objects) dataset.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/openmmlab/upernet-convnext-small",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        mask_threshold 	number 	Threshold to use when turning the predicted masks into binary values.
        overlap_mask_area_threshold 	number 	Mask overlap threshold to eliminate small, disconnected segments.
        subtask 	enum 	Possible values: instance, panoptic, semantic.
        threshold 	number 	Probability threshold to filter out predicted masks.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	A predicted mask / segment
        label 	string 	The label of the predicted segment.
        mask 	string 	The corresponding mask as a black-and-white image (base64-encoded).
        score 	number 	The score or confidence degree the model has.
< > Update on GitHub

Image Classification
←Image Classification
Image to Image→

Image to Image

Image-to-image is the task of transforming a source image to match the characteristics of a target image or a target image domain.

Example applications:

    Transferring the style of an image to another image
    Colorizing a black and white image
    Increasing the resolution of an image

For more details about the image-to-image task, check out its dedicated page! You will find examples and related materials.
Recommended models

    timbrooks/instruct-pix2pix: A model that takes an image and an instruction to edit the image.

Explore all available models and find the one that suits you best here.
Using the API

No snippet available for this task.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        guidance_scale 	number 	For diffusion models. A higher guidance scale value encourages the model to generate images closely linked to the text prompt at the expense of lower image quality.
        negative_prompt 	string[] 	One or several prompt to guide what NOT to include in image generation.
        num_inference_steps 	integer 	For diffusion models. The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.
        target_size 	object 	The size in pixel of the output image.
                width* 	integer 	
                height* 	integer 	

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
image 	unknown 	The output image returned as raw bytes in the payload.
< > Update on GitHub

Image Segmentation
←Image Segmentation
Image-Text to Text→Image-Text to Text

Image-text-to-text models take in an image and text prompt and output text. These models are also called vision-language models, or VLMs. The difference from image-to-text models is that these models take an additional text input, not restricting the model to certain use cases like image captioning, and may also be trained to accept a conversation as input.

For more details about the image-text-to-text task, check out its dedicated page! You will find examples and related materials.
Recommended models

    meta-llama/Llama-3.2-11B-Vision-Instruct: Powerful vision language model with great visual understanding and reasoning capabilities.
    Qwen/Qwen2-VL-7B-Instruct: Strong image-text-to-text model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/meta-llama/Llama-3.2-11B-Vision-Instruct",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Can you please let us know more details about your "}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification

For the API specification of conversational image-text-to-text models, please refer to the Chat Completion API documentation.
< > Update on GitHub

Image-Text to Text
←Image to Image
Object Detection→Object detection

Object Detection models allow users to identify objects of certain defined classes. These models receive an image as input and output the images with bounding boxes and labels on detected objects.

For more details about the object-detection task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/detr-resnet-50: Solid object detection model pre-trained on the COCO 2017 dataset.

Explore all available models and find the one that suits you best here.
Using the API

async function query(filename) {
	const data = fs.readFileSync(filename);
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/detr-resnet-50",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: data,
		}
	);
	const result = await response.json();
	return result;
}

query("cats.jpg").then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input image data as a base64-encoded string. If no parameters are provided, you can also provide the image data as a raw bytes payload.
parameters 	object 	
        threshold 	number 	The probability necessary to make a prediction.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted label for the bounding box.
        score 	number 	The associated score / probability.
        box 	object 	
                xmin 	integer 	The x-coordinate of the top-left corner of the bounding box.
                xmax 	integer 	The x-coordinate of the bottom-right corner of the bounding box.
                ymin 	integer 	The y-coordinate of the top-left corner of the bounding box.
                ymax 	integer 	The y-coordinate of the bottom-right corner of the bounding box.
< > Update on GitHub

Image-Text to Text
←Image-Text to Text
Question Answering→

Question Answering

Question Answering models can retrieve the answer to a question from a given text, which is useful for searching for an answer in a document.

For more details about the question-answering task, check out its dedicated page! You will find examples and related materials.
Recommended models

    deepset/roberta-base-squad2: A robust baseline model for most question answering domains.
    distilbert/distilbert-base-cased-distilled-squad: Small yet robust model that can answer questions.
    google/tapas-base-finetuned-wtq: A special model that can answer questions from tables.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/deepset/roberta-base-squad2",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": {
	"question": "What is my name?",
	"context": "My name is Clara and I live in Berkeley."
}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	object 	One (context, question) pair to answer
        context* 	string 	The context to be used for answering the question
        question* 	string 	The question to be answered
parameters 	object 	
        top_k 	integer 	The number of answers to return (will be chosen by order of likelihood). Note that we return less than topk answers if there are not enough options available within the context.
        doc_stride 	integer 	If the context is too long to fit with the question for the model, it will be split in several chunks with some overlap. This argument controls the size of that overlap.
        max_answer_len 	integer 	The maximum length of predicted answers (e.g., only answers with a shorter length are considered).
        max_seq_len 	integer 	The maximum length of the total sentence (context + question) in tokens of each chunk passed to the model. The context will be split in several chunks (using docStride as overlap) if needed.
        max_question_len 	integer 	The maximum length of the question after tokenization. It will be truncated if needed.
        handle_impossible_answer 	boolean 	Whether to accept impossible as an answer.
        align_to_words 	boolean 	Attempts to align the answer to real words. Improves quality on space separated languages. Might hurt on non-space-separated languages (like Japanese or Chinese)

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        answer 	string 	The answer to the question.
        score 	number 	The probability associated to the answer.
        start 	integer 	The character position in the input where the answer begins.
        end 	integer 	The character position in the input where the answer ends.
< > Update on GitHub

Object detection
←Object Detection
Summarization→

Summarization

Summarization is the task of producing a shorter version of a document while preserving its important information. Some models can extract text from the original input, while other models can generate entirely new text.

For more details about the summarization task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/bart-large-cnn: A strong summarization model trained on English news articles. Excels at generating factual summaries.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/bart-large-cnn",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "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. It was the first structure to reach a height of 300 metres. Due to the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the Chrysler Building by 5.2 metres (17 ft). Excluding transmitters, the Eiffel Tower is the second tallest free-standing structure in France after the Millau Viaduct."}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text to summarize.
parameters 	object 	
        clean_up_tokenization_spaces 	boolean 	Whether to clean up the potential extra spaces in the text output.
        truncation 	enum 	Possible values: do_not_truncate, longest_first, only_first, only_second.
        generate_parameters 	object 	Additional parametrization of the text generation algorithm.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
summary_text 	string 	The summarized text.
< > Update on GitHub

Question Answering
←Question Answering
Table Question Answering→

Table Question Answering

Table Question Answering (Table QA) is the answering a question about an information on a given table.

For more details about the table-question-answering task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/tapas-base-finetuned-wtq: A robust table question answering model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/tapas-base-finetuned-wtq",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": {
	"query": "How many stars does the transformers repository have?",
	"table": {
		"Repository": ["Transformers", "Datasets", "Tokenizers"],
		"Stars": ["36542", "4512", "3934"],
		"Contributors": ["651", "77", "34"],
		"Programming language": [
			"Python",
			"Python",
			"Rust, Python and NodeJS"
		]
	}
}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	object 	One (table, question) pair to answer
        table* 	object 	The table to serve as context for the questions
        question* 	string 	The question to be answered about the table
parameters 	object 	
        padding 	enum 	Possible values: do_not_pad, longest, max_length.
        sequential 	boolean 	Whether to do inference sequentially or as a batch. Batching is faster, but models like SQA require the inference to be done sequentially to extract relations within sequences, given their conversational nature.
        truncation 	boolean 	Activates and controls truncation.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        answer 	string 	The answer of the question given the table. If there is an aggregator, the answer will be preceded by AGGREGATOR >.
        coordinates 	array[] 	Coordinates of the cells of the answers.
        cells 	string[] 	List of strings made up of the answer cell values.
        aggregator 	string 	If the model has an aggregator, this returns the aggregator.
< > Update on GitHub

Summarization
←Summarization
Text Classification→Text Classification

Text Classification is the task of assigning a label or class to a given text. Some use cases are sentiment analysis, natural language inference, and assessing grammatical correctness.

For more details about the text-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    distilbert/distilbert-base-uncased-finetuned-sst-2-english: A robust model trained for sentiment analysis.
    ProsusAI/finbert: A sentiment analysis model specialized in financial sentiment.
    cardiffnlp/twitter-roberta-base-sentiment-latest: A sentiment analysis model specialized in analyzing tweets.
    papluca/xlm-roberta-base-language-detection: A model that can classify languages.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/distilbert/distilbert-base-uncased-finetuned-sst-2-english",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "I like you. I love you"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to classify
parameters 	object 	
        function_to_apply 	enum 	Possible values: sigmoid, softmax, none.
        top_k 	integer 	When specified, limits the output to the top K most probable classes.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Table Question Answering
←Table Question Answering
Text Generation→

Text Generation

Generate text based on a prompt.

If you are interested in a Chat Completion task, which generates a response based on a list of messages, check out the chat-completion task.

For more details about the text-generation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google/gemma-2-2b-it: A text-generation model trained to follow instructions.
    meta-llama/Meta-Llama-3.1-8B-Instruct: Very powerful text generation model trained to follow instructions.
    microsoft/Phi-3-mini-4k-instruct: Small yet powerful text generation model.
    Qwen/Qwen2.5-7B-Instruct: Strong text generation model to follow instructions.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google/gemma-2-2b-it",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Can you please let us know more details about your "}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	
parameters 	object 	
        adapter_id 	string 	Lora adapter id
        best_of 	integer 	Generate best_of sequences and return the one if the highest token logprobs.
        decoder_input_details 	boolean 	Whether to return decoder input token logprobs and ids.
        details 	boolean 	Whether to return generation details.
        do_sample 	boolean 	Activate logits sampling.
        frequency_penalty 	number 	The parameter for frequency penalty. 1.0 means no penalty Penalize new tokens based on their existing frequency in the text so far, decreasing the model’s likelihood to repeat the same line verbatim.
        grammar 	unknown 	One of the following:
                 (#1) 	object 	
                        type* 	enum 	Possible values: json.
                        value* 	unknown 	A string that represents a JSON Schema. JSON Schema is a declarative language that allows to annotate JSON documents with types and descriptions.
                 (#2) 	object 	
                        type* 	enum 	Possible values: regex.
                        value* 	string 	
        max_new_tokens 	integer 	Maximum number of tokens to generate.
        repetition_penalty 	number 	The parameter for repetition penalty. 1.0 means no penalty. See this paper for more details.
        return_full_text 	boolean 	Whether to prepend the prompt to the generated text
        seed 	integer 	Random sampling seed.
        stop 	string[] 	Stop generating tokens if a member of stop is generated.
        temperature 	number 	The value used to module the logits distribution.
        top_k 	integer 	The number of highest probability vocabulary tokens to keep for top-k-filtering.
        top_n_tokens 	integer 	The number of highest probability vocabulary tokens to keep for top-n-filtering.
        top_p 	number 	Top-p value for nucleus sampling.
        truncate 	integer 	Truncate inputs tokens to the given size.
        typical_p 	number 	Typical Decoding mass See Typical Decoding for Natural Language Generation for more information.
        watermark 	boolean 	Watermarking with A Watermark for Large Language Models.
stream 	boolean 	

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
details 	object 	
        best_of_sequences 	object[] 	
                finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
                generated_text 	string 	
                generated_tokens 	integer 	
                prefill 	object[] 	
                        id 	integer 	
                        logprob 	number 	
                        text 	string 	
                seed 	integer 	
                tokens 	object[] 	
                        id 	integer 	
                        logprob 	number 	
                        special 	boolean 	
                        text 	string 	
                top_tokens 	array[] 	
                        id 	integer 	
                        logprob 	number 	
                        special 	boolean 	
                        text 	string 	
        finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
        generated_tokens 	integer 	
        prefill 	object[] 	
                id 	integer 	
                logprob 	number 	
                text 	string 	
        seed 	integer 	
        tokens 	object[] 	
                id 	integer 	
                logprob 	number 	
                special 	boolean 	
                text 	string 	
        top_tokens 	array[] 	
                id 	integer 	
                logprob 	number 	
                special 	boolean 	
                text 	string 	
generated_text 	string 	

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
Body 		
details 	object 	
        finish_reason 	enum 	Possible values: length, eos_token, stop_sequence.
        generated_tokens 	integer 	
        input_length 	integer 	
        seed 	integer 	
generated_text 	string 	
index 	integer 	
token 	object 	
        id 	integer 	
        logprob 	number 	
        special 	boolean 	
        text 	string 	
top_tokens 	object[] 	
        id 	integer 	
        logprob 	number 	
        special 	boolean 	
        text 	string 	
< > Update on GitHub

Text Classification
←Text Classification
Text to Image→

Text to Image

Generate an image based on a given text prompt.

For more details about the text-to-image task, check out its dedicated page! You will find examples and related materials.
Recommended models

    black-forest-labs/FLUX.1-dev: One of the most powerful image generation models that can generate realistic outputs.
    stabilityai/stable-diffusion-3-medium-diffusers: A powerful text-to-image model.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/black-forest-labs/FLUX.1-dev",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.blob();
	return result;
}
query({"inputs": "Astronaut riding a horse"}).then((response) => {
	// Use image
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text data (sometimes called “prompt”)
parameters 	object 	
        guidance_scale 	number 	A higher guidance scale value encourages the model to generate images closely linked to the text prompt, but values too high may cause saturation and other artifacts.
        negative_prompt 	string[] 	One or several prompt to guide what NOT to include in image generation.
        num_inference_steps 	integer 	The number of denoising steps. More denoising steps usually lead to a higher quality image at the expense of slower inference.
        target_size 	object 	The size in pixel of the output image
                width* 	integer 	
                height* 	integer 	
        scheduler 	string 	Override the scheduler with a compatible one.
        seed 	integer 	Seed for the random number generator.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
image 	unknown 	The generated image returned as raw bytes in the payload.
< > Update on GitHub

Text Generation
←Text Generation
Token Classification→

Token Classification

Token classification is a task in which a label is assigned to some tokens in a text. Some popular token classification subtasks are Named Entity Recognition (NER) and Part-of-Speech (PoS) tagging.

For more details about the token-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    dslim/bert-base-NER: A robust performance model to identify people, locations, organizations and names of miscellaneous entities.
    FacebookAI/xlm-roberta-large-finetuned-conll03-english: A strong model to identify people, locations, organizations and names in multiple languages.
    blaze999/Medical-NER: A token classification model specialized on medical entity recognition.
    flair/ner-english: Flair models are typically the state of the art in named entity recognition tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/dslim/bert-base-NER",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "My name is Sarah Jessica Parker but you can call me Jessica"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The input text data
parameters 	object 	
        ignore_labels 	string[] 	A list of labels to ignore
        stride 	integer 	The number of overlapping tokens between chunks when splitting the input text.
        aggregation_strategy 	string 	One of the following:
                 (#1) 	’none’ 	Do not aggregate tokens
                 (#2) 	’simple’ 	Group consecutive tokens with the same label in a single entity.
                 (#3) 	’first’ 	Similar to “simple”, also preserves word integrity (use the label predicted for the first token in a word).
                 (#4) 	’average’ 	Similar to “simple”, also preserves word integrity (uses the label with the highest score, averaged across the word’s tokens).
                 (#5) 	’max’ 	Similar to “simple”, also preserves word integrity (uses the label with the highest score across the word’s tokens).

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response

Output type depends on the stream input parameter. If stream is false (default), the response will be a JSON object with the following fields:
Body 		
(array) 	object[] 	Output is an array of objects.
        entity_group 	string 	The predicted label for a group of one or more tokens
        entity 	string 	The predicted label for a single token
        score 	number 	The associated score / probability
        word 	string 	The corresponding text
        start 	integer 	The character position in the input where this group begins.
        end 	integer 	The character position in the input where this group ends.

If stream is true, generated tokens are returned as a stream, using Server-Sent Events (SSE). For more information about streaming, check out this guide.
< > Update on GitHub

Token Classification
←Text to Image
Translation→

Translation

Translation is the task of converting text from one language to another.

For more details about the translation task, check out its dedicated page! You will find examples and related materials.
Recommended models

    google-t5/t5-base: A general-purpose Transformer that can be used to translate from English to German, French, or Romanian.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/google-t5/t5-base",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Меня зовут Вольфганг и я живу в Берлине"}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to translate.
parameters 	object 	
        src_lang 	string 	The source language of the text. Required for models that can translate from multiple languages.
        tgt_lang 	string 	Target language to translate to. Required for models that can translate to multiple languages.
        clean_up_tokenization_spaces 	boolean 	Whether to clean up the potential extra spaces in the text output.
        truncation 	enum 	Possible values: do_not_truncate, longest_first, only_first, only_second.
        generate_parameters 	object 	Additional parametrization of the text generation algorithm.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
translation_text 	string 	The translated text.
< > Update on GitHub

Token Classification
←Token Classification
Zero Shot Classification→Zero-Shot Classification

Zero-shot text classification 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. The model has not been necessarily trained on the labels you provide, but it can still predict the correct label.

For more details about the zero-shot-classification task, check out its dedicated page! You will find examples and related materials.
Recommended models

    facebook/bart-large-mnli: Powerful zero-shot text classification model.
    MoritzLaurer/mDeBERTa-v3-base-xnli-multilingual-nli-2mil7: Powerful zero-shot multilingual text classification model that can accomplish multiple tasks.

Explore all available models and find the one that suits you best here.
Using the API

async function query(data) {
	const response = await fetch(
		"https://api-inference.huggingface.co/models/facebook/bart-large-mnli",
		{
			headers: {
				Authorization: "Bearer hf_***",
				"Content-Type": "application/json",
			},
			method: "POST",
			body: JSON.stringify(data),
		}
	);
	const result = await response.json();
	return result;
}

query({"inputs": "Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!", "parameters": {"candidate_labels": ["refund", "legal", "faq"]}}).then((response) => {
	console.log(JSON.stringify(response));
});

To use the JavaScript client, see huggingface.js’s package reference.
API specification
Request
Payload 		
inputs* 	string 	The text to classify
parameters* 	object 	
        candidate_labels* 	string[] 	The set of possible class labels to classify the text into.
        hypothesis_template 	string 	The sentence used in conjunction with candidate_labels to attempt the text classification by replacing the placeholder with the candidate labels.
        multi_label 	boolean 	Whether multiple candidate labels can be true. If false, the scores are normalized such that the sum of the label likelihoods for each sequence is 1. If true, the labels are considered independent and probabilities are normalized for each candidate.

Some options can be configured by passing headers to the Inference API. Here are the available headers:
Headers 		
authorization 	string 	Authentication header in the form 'Bearer: hf_****' when hf_**** is a personal user access token with Inference API permission. You can generate one from your settings page.
x-use-cache 	boolean, default to true 	There is a cache layer on the inference API to speed up requests we have already seen. Most models can use those results as they are deterministic (meaning the outputs will be the same anyway). However, if you use a nondeterministic model, you can set this parameter to prevent the caching mechanism from being used, resulting in a real new query. Read more about caching here.
x-wait-for-model 	boolean, default to false 	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. Read more about model availability here.

For more information about Inference API headers, check out the parameters guide.
Response
Body 		
(array) 	object[] 	Output is an array of objects.
        label 	string 	The predicted class label.
        score 	number 	The corresponding probability.
< > Update on GitHub

Zero-Shot Classification
←Translation
Getting Started→

""".



Generate a single, comprehensive code snippet in one code block that integrates all functionalities described in the Hugging Face Serverless Inference API documentation into a cohesive JavaScript program. The code should include:

    Text Generation: Use a large language model to generate humorous or interesting responses based on a prompt. Ensure correct handling of the JSON response to obtain the generated text.

    Text Classification: Implement sentiment analysis on a text input using a dedicated model. The snippet should show how to send the text to the relevant API endpoint and extract the classification results.

    Image Generation: Create an image based on a descriptive text prompt. Include all necessary parameters and ensure that the output is correctly displayed.

    Audio Classification: Allow for classification of audio clips using an appropriate model. The code should include a placeholder for audio input and demonstrate how to send the audio to the API for classification.

    Automatic Speech Recognition (ASR): Include functionality to transcribe audio files into text. The program should send audio data and handle the response to output the transcription.

    Question Answering: Show how to answer a question based on provided context using a question answering model. Ensure that the input structure matches the expected API requirements.

    Zero-Shot Classification: Demonstrate classification of text into predetermined categories without prior model training on those categories. Provide an example of how to set up this call.

    Cache Control: Integrate an x-use-cache header in all API calls set to false to ensure that no cached results are used, retrieving fresh outputs on each request.

    Error Handling: Implement robust error handling to capture and display API errors gracefully, should they occur during any of the operations.

    Execution in a Web Environment: Ensure that the entire code snippet is compatible with execution in a web browser environment using async/await for asynchronous API calls.

The final code block should clearly demonstrate all the above functionalities within a structured and executable format.

strictly working/functioning  html/css/javascript in one codeblock.
utilise this key in code you generating: <TRUFFLEHOG_REDACTED_HUGGINGFACE>

outshow strictly working/functioning code.
no comments.