Huggingface X Hyperbolic

This documentation provides a concise guide for developers to integrate and use Hyperbolic inference capabilities via the Hugging Face ecosystem.

Authentication and Billing

When using Hyperbolic through Hugging Face, you have two options for authentication:

Direct Requests: Use your Hyperbolic API key in your Hugging Face user account settings. In this mode, inference requests are sent directly to Hyperbolic, and billing is handled by your Hyperbolic account.
Routed Requests: If you don't configure a Hyperbolic API key, your requests will be routed through Hugging Face. In this case, you can use a Hugging Face token for authentication. Billing for routed requests is applied to your Hugging Face account at standard provider API rates.You don’t need an account on Hyperbolic to do this, just use your HF one!

To add a Hyperbolic api key to your Hugging Face settings, follow these steps:

Go to your Hugging Face user account settings .
Locate the "Inference Providers" section.
You can add your API keys for different providers, including Hyperbolic
You can also set your preferred provider order, which will influence the display order in model widgets and code snippets.

You can search for all Hyperbolic Models on the hub and directly try out the available models via the Model Page widget too.

Usage Examples

The examples below demonstrate how to interact with various models using Python and JavaScript.

Python

First, ensure you have the huggingface_hub library installed (version v0.29.0 or later):

pip install huggingface_hub>=0.29.0

Chat Completions (LLMs) with Hugging Face Hub library

from huggingface_hub import InferenceClient

# Initialize the InferenceClient with Hyperbolic as the provider
client = InferenceClient(  
    provider="hyperbolic",  
    api_key="xxxxxxxxxxxxxxxxxxxxxxxx"  # Replace with your API key (HF or custom)  
)

# Define the chat messages
messages = [  
    {  
        "role": "user",  
        "content": "What is the capital of France?"  
    }  
]

# Generate a chat completion
completion = client.chat.completions.create(  
    model="deepseek-ai/DeepSeek-R1",  
    messages=messages,  
    max_tokens=500  
)

# Print the response
print(completion.choices[0].message)

You can swap this for any compatible LLM from Hyperbolic, here’s a handy URL to find the list:

Text-to-Image Generation

from huggingface_hub import InferenceClient

client = InferenceClient(  
    provider="hyperbolic",  
    api_key="xxxxxxxxxxxxxxxxxxxxxxxx"  # Replace with your API key  
)

# Generate an image from text
image = client.text_to_image(  
    "Bob Marley in the style of a painting by Johannes Vermeer",  
    model="Qwen/Qwen2.5-VL-7B-Instruct"  # Replace with your desired model  
)

# `image` is a PIL.Image object
image.show()

Similar to LLMs, you can use any compatible Text to Image model from the list here:

You can also call inference providers via the OpenAI python client . You will need to specify the base_url and model parameters in the client and call respectively.

The easiest way is to go to a model’s page on the hub and copy the snippet.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/hyperbolic/v1",
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-R1",
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
)

print(completion.choices[0].message)

JavaScript

First, install the @huggingface/inference package:

npm install @huggingface/inference

[Chat Completion with Hugging Face Hub

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

// Initialize the HfInference client with your API key  
const client = new HfInference("xxxxxxxxxxxxxxxxxxxxxxxx");

// Generate a chat completion  
const chatCompletion = await client.chatCompletion({  
    model: "deepseek-ai/DeepSeek-R1",  // Replace with your desired model  
    messages: [  
        {  
            role: "user",  
            content: "What is the capital of France?"  
        }  
    ],  
    provider: "hyperbolic",  
    max_tokens: 500  
});

// Log the response  
console.log(chatCompletion.choices[0].message);

Text-to-Image Generation

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

// Initialize the HfInference client with your API key  
const client = new HfInference("xxxxxxxxxxxxxxxxxxxxxxxx");

// Generate a chat completion  
const generatedImage = await client.textToImage({  
    model: "Qwen/Qwen2.5-VL-7B-Instruct",  // Replace with your desired model  
    inputs: "Bob Marley in the style of a painting by Johannes Vermeer",    
    provider: "hyperbolic", 
    max_tokens: 500  
});

You can search for all Hyperbolic models on the hub and directly try out the available models via the Model Page widget too.

We’ll continue to increase the number of models and ways to try it out!