Code beginner · 3 min read

How to call Hugging Face model via API in python

Direct answer

Use the Hugging Face Inference API by sending a POST request with your input text and API key via Python's requests library to the model endpoint URL.

Setup

Install

bash

pip install requests

Env vars

HF_API_KEY

Imports

python

import os
import requests

Examples

inTranslate 'Hello, how are you?' to French

outBonjour, comment ça va ?

inSummarize the text: 'Hugging Face provides state-of-the-art NLP models.'

outHugging Face offers advanced NLP models.

inGenerate a short poem about spring

outSpring blooms anew, bright skies and fresh dew.

Integration steps

Set your Hugging Face API key in the environment variable HF_API_KEY
Construct the API endpoint URL for the desired model
Prepare the input payload as JSON with the text or data to process
Send a POST request with headers including Authorization Bearer token
Parse the JSON response to extract the generated text output

Full code

python

import os
import requests

# Load API key from environment
api_key = os.environ.get('HF_API_KEY')
if not api_key:
    raise ValueError('Set the HF_API_KEY environment variable')

# Define the model endpoint (example: facebook/bart-large-cnn for summarization)
model_id = 'facebook/bart-large-cnn'
api_url = f'https://api-inference.huggingface.co/models/{model_id}'

# Input text to process
input_text = "Hugging Face provides state-of-the-art NLP models."

# Prepare headers with authorization
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Prepare payload
payload = {
    'inputs': input_text
}

# Make the POST request
response = requests.post(api_url, headers=headers, json=payload)

# Check for successful response
response.raise_for_status()

# Parse the JSON response
result = response.json()

# Extract generated text (depends on model output format)
# For summarization models, result is usually a list of dicts with 'summary_text'
if isinstance(result, list) and 'summary_text' in result[0]:
    output_text = result[0]['summary_text']
else:
    output_text = str(result)

print('Model output:', output_text)

output

Model output: Hugging Face offers advanced NLP models.

API trace

Request

json

{"inputs": "Your input text here"}

Response

json

[{"summary_text": "Generated summary or output text"}]

Extractresponse.json()[0]['summary_text']

Variants

Streaming response with Hugging Face Inference API ›

Use streaming when generating long text outputs to receive partial results progressively.

python

import os
import requests

api_key = os.environ.get('HF_API_KEY')
model_id = 'gpt2'
api_url = f'https://api-inference.huggingface.co/models/{model_id}'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

payload = {'inputs': 'Once upon a time'}

with requests.post(api_url, headers=headers, json=payload, stream=True) as response:
    response.raise_for_status()
    for chunk in response.iter_content(chunk_size=1024):
        if chunk:
            print(chunk.decode('utf-8'), end='')

Async call using httpx for concurrent requests ›

Use async calls to handle multiple concurrent Hugging Face API requests efficiently.

python

import os
import asyncio
import httpx

async def call_hf_model(text):
    api_key = os.environ.get('HF_API_KEY')
    model_id = 'facebook/bart-large-cnn'
    api_url = f'https://api-inference.huggingface.co/models/{model_id}'
    headers = {'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}
    async with httpx.AsyncClient() as client:
        response = await client.post(api_url, headers=headers, json={'inputs': text})
        response.raise_for_status()
        result = response.json()
        return result[0]['summary_text'] if isinstance(result, list) else str(result)

async def main():
    summary = await call_hf_model('Hugging Face provides state-of-the-art NLP models.')
    print('Async model output:', summary)

asyncio.run(main())

Alternative model endpoint for text generation ›

Use a text generation model like GPT-2 for creative or open-ended text completions.

python

import os
import requests

api_key = os.environ.get('HF_API_KEY')
model_id = 'gpt2'
api_url = f'https://api-inference.huggingface.co/models/{model_id}'
headers = {'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}
payload = {'inputs': 'The future of AI is'}
response = requests.post(api_url, headers=headers, json=payload)
response.raise_for_status()
result = response.json()
print('Generated text:', result[0]['generated_text'] if 'generated_text' in result[0] else result)

Performance

Latency~1-3 seconds per request depending on model size and server load

CostCheck Hugging Face pricing; inference API calls may incur charges based on usage

Rate limitsDefault limits vary by account; typically hundreds of requests per minute

Send only necessary input text to reduce payload size
Use smaller or distilled models for faster and cheaper inference
Batch multiple inputs if supported to optimize throughput

Approach	Latency	Cost/call	Best for
Standard POST request	~1-3s	Varies by model	Simple synchronous calls
Streaming response	Faster perceived latency	Similar	Long text generation
Async calls	Concurrent requests	Similar	High throughput or parallelism

✓

Quick tip

Always set your Hugging Face API key in an environment variable and never hardcode it in your code.

⚠

Common mistake

Forgetting to include the 'Authorization' header with the Bearer token causes 401 Unauthorized errors.

Verified 2026-04 · facebook/bart-large-cnn, gpt2

Verify ↗

Community Notes

No notes yetBe the first to share a version-specific fix or tip.