Skip to main content

​
Quick Start

Get started with Hugging Face in under 2 minutes: 
from portkey_ai import Portkey

# 1. Install: pip install portkey-ai
# 2. Add @huggingface provider in model catalog
# 3. Use it:

portkey = Portkey(api_key="PORTKEY_API_KEY")

response = portkey.chat.completions.create(
    model="@huggingface/meta-llama/Llama-3.2-3B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

import Portkey from 'portkey-ai'

// 1. Install: npm install portkey-ai
// 2. Add @huggingface provider in model catalog
// 3. Use it:

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY"
})

const response = await portkey.chat.completions.create({
    model: "@huggingface/meta-llama/Llama-3.2-3B-Instruct",
    messages: [{ role: "user", content: "Hello!" }]
})

console.log(response.choices[0].message.content)

from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL

# 1. Install: pip install openai portkey-ai
# 2. Add @huggingface provider in model catalog
# 3. Use it:

client = OpenAI(
    api_key="PORTKEY_API_KEY",  # Portkey API key
    base_url=PORTKEY_GATEWAY_URL
)

response = client.chat.completions.create(
    model="@huggingface/meta-llama/Llama-3.2-3B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

import OpenAI from "openai"
import { PORTKEY_GATEWAY_URL } from "portkey-ai"

// 1. Install: npm install openai portkey-ai
// 2. Add @huggingface provider in model catalog
// 3. Use it:

const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",  // Portkey API key
    baseURL: PORTKEY_GATEWAY_URL
})

const response = await client.chat.completions.create({
    model: "@huggingface/meta-llama/Llama-3.2-3B-Instruct",
    messages: [{ role: "user", content: "Hello!" }]
})

console.log(response.choices[0].message.content)

# 1. Add @huggingface provider in model catalog
# 2. Use it:

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -d '{
    "model": "@huggingface/meta-llama/Llama-3.2-3B-Instruct",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

​
Add Provider in Model Catalog

Before making requests, add Hugging Face to your Model Catalog:
  1. Go to Model Catalog → Add Provider
  2. Select Hugging Face
  3. Enter your Hugging Face access token
  4. (Optional) Add a Custom Host if using a dedicated Hugging Face Inference Endpoint (e.g., https://your-custom-url/v1)
  5. Name your provider (e.g., huggingface)
If you have a dedicated server hosted on Hugging Face, enter your dedicated endpoint URL in the Custom Host field during provider setup. This allows you to route requests to your private Hugging Face deployment.

Complete Setup Guide

See all setup options and detailed configuration instructions

​
Supported Models

Hugging Face provides access to thousands of text generation models through their Inference endpoints, including:
  • Meta Llama 3.2, Llama 3.1, Llama 3
  • Mistral, Mixtral
  • Qwen 2.5
  • Phi-3
  • Gemma, Gemma 2
  • And thousands more!
Browse the complete catalog at Hugging Face Models.

​
Next Steps

Gateway Configs

Add fallbacks, load balancing, and more

Observability

Monitor and trace your Hugging Face requests

Prompt Library

Manage and version your prompts

Metadata

Add custom metadata to requests
For complete SDK documentation:

SDK Reference

Complete Portkey SDK documentation
Last modified on March 13, 2026