hfgo

An unofficial Go SDK for the Hugging Face Inference API. Directly call any model available in the Model Hub.

An API key is required for authorized access. To get one, create a Hugging Face account and generate a token.

⚠️ v4 Release Candidate

v4 is currently in release candidate status (v4.0.0-rc1). The API may evolve before the final v4.0.0 release. v3 and earlier are deprecated and no longer maintained. See #72 for more information.

Usage

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/Kardbord/hfgo/v4"
	"github.com/Kardbord/hfgo/v4/hfopts"
	"github.com/Kardbord/hfgo/v4/hftypes"
)

func main() {
	token := os.Getenv("HF_TOKEN")
	if token == "" {
		log.Fatal("HF_TOKEN environment variable is not set")
	}

	client := hfgo.NewClient(
		hfopts.WithToken(token),
		hfopts.WithModel("deepseek-ai/DeepSeek-R1"),
	)

	request := hftypes.ChatRequest{
		Messages: []hftypes.ChatMessage{
			{
				Role: "user",
				Content: hftypes.ChatMessageContent{
					Text: Ptr("Hello! What is the capital of France?"),
				},
			},
		},
		MaxTokens: Ptr(1024),
	}

	response, err := client.Chat(request)
	if err != nil {
		log.Fatalf("Failed to complete chat request: %v", err)
	}

	for _, choice := range response.Choices {
		if choice.Message.Content != nil {
			fmt.Println(*choice.Message.Content)
		}
	}
}

func Ptr[T any](v T) *T {
	return &v
}

See the examples directory for more.

Providers

Requests are routed through a pluggable inference-provider layer (the hfproviders package). The default HuggingFaceProvider speaks the HuggingFace wire format directly, so for most use cases nothing needs to be configured.

• Use hfopts.WithProvider(p) to set an explicit provider on a client or a single call, and hfopts.WithDefaultProvider() to use the default HuggingFace provider.
• On OpenAI-compatible endpoints (e.g. chat completions), a provider or selection policy can be pinned by appending a suffix to the model string (e.g. model:sambanova, model:fastest, model:cheapest, model:preferred); otherwise the HF router selects the provider. See https://huggingface.co/docs/inference-providers/main/en/index.

client := hfgo.NewClient(
	hfopts.WithToken(token),
	hfopts.WithModel("deepseek-ai/DeepSeek-R1"),
	hfopts.WithDefaultProvider(),
)

Inference Tasks

• Chat
• Fill Mask
• Question Answering
• Summarization
• Table Question Answering
• Text Classification
• Token Classification
• Translation
• Zero-Shot Text Classification

Contributing

Contributions are welcome in many forms!

• Opening or commenting on issues to suggest new features, clarify requirements, and report bugs
• Reviewing PRs to help improve code quality
• Documentation improvements (updating README, docs/, or examples/)
• Community engagement (helping new contributors, answering questions)

If you plan to contribute code, please open an issue first to discuss your proposed changes, coordinate with maintainers, and avoid duplicate work.

See CONTRIBUTING.md for detailed guidelines.

Resources

• Hugging Face
• Inference API JSON Schemas
• Model Hub
• Datasets
• Hugging Face Inference API
• HF on GitHub
  • Official Python SDK
  • Official JavaScript SDK