Skip to content
Projects

Kardbord/hfgo has 64 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-15 15:37 UTC. Last push 2026-11-06.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
0
in 15 days
0
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

An unofficial Go SDK for the Hugging Face Inference API.

Creative & Media

README.md

Original

hfgo

Build Unit Tests Integration Tests Lint Fuzz Tests CodeQL Code Coverage Go Reference OpenSSF Scorecard OpenSSF Best Practices

An unofficial Go SDK for the Hugging Face Inference API. It provides type-safe client methods for every supported inference task and a pluggable provider layer for alternate wire formats.

⚠️ v4 Release Candidate

v4 is currently in release candidate status. 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.

Requirements

  • Go 1.27 or later.
  • A Hugging Face API key. To get one, create a Hugging Face account and generate a token. Examples and integration tests read the token from the HF_TOKEN environment variable.

Quickstart

go get github.com/Kardbord/hfgo/v4@latest
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() {
	client := hfgo.NewClient(
		hfopts.WithToken(os.Getenv("HF_TOKEN")),
		hfopts.WithModel("deepseek-ai/DeepSeek-R1"),
	)

	response, err := client.Chat(hftypes.ChatRequest{
		Messages: []hftypes.ChatMessage{
			{
				Role:    "user",
				Content: hftypes.ChatMessageContent{
					Text: new("Hello! What is the capital of France?"),
				},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	if len(response.Choices) > 0 && response.Choices[0].Message.Content != nil {
		fmt.Println(*response.Choices[0].Message.Content)
	}

	// Other tasks follow this shape. See examples/huggingface/speech-recognition,
	// examples/huggingface/text-classification, and the rest of examples/ for more.
}

Every task works this way: build a client, send a typed request, read a typed response or error. The examples directory has a runnable program for each task and variant.

One client, many tasks

A client is not tied to a single task or model. The token, base URL, provider, and HTTP configuration are shared, so the same client you use for speech recognition is the client you use for text classification. Because each task needs its own model, supply the model per call when it differs from the client default:

client := hfgo.NewClient(hfopts.WithToken(os.Getenv("HF_TOKEN")))

// Automatic speech recognition — model supplied per call.
transcript, err := client.RecognizeSpeech(
	hftypes.SpeechRecognitionRequest{Input: audioBase64},
	hfopts.WithModel("openai/whisper-large-v3"),
)

// Text classification — same client, different model.
labels, err := client.ClassifyText(
	hftypes.TextClassificationRequest{Input: "A delightful surprise."},
	hfopts.WithModel("ProsusAI/finbert"),
)

Alternatively, create the client with a model and override it per call only where needed. See Options precedence.

Inference Tasks

Each link points to a runnable example. Most tasks have several variants (basic, params, batch, streaming, conversation); see the examples README for the convention.

Partner providers have their own examples:

  • WaveSpeed — text-to-video, text-to-image, and image-to-image through WaveSpeed.
  • Fal AI — text-to-image, image-to-image, text-to-video, image-segmentation, and speech-recognition through Fal AI.
  • DeepInfra — chat completions (unary, streaming, and multi-turn conversation) plus speech recognition and pooled feature extraction through DeepInfra.
  • Together — chat completions (unary, streaming, and multi-turn conversation) pinned to Together.
  • Nscale — chat completions (unary, streaming, and multi-turn conversation) plus text-to-image (Hub and static resolvers) through Nscale.
  • Scaleway — chat completions (unary, streaming, and multi-turn conversation) plus pooled feature extraction through Scaleway.
  • Replicate — text-to-image, image-to-image, text-to-video, and speech recognition through Replicate.
  • Baseten — chat completions (unary, streaming, and multi-turn conversation) pinned to Baseten.
  • Cerebras — chat completions (unary, streaming, and multi-turn conversation) pinned to Cerebras.
  • Cohere — chat completions (unary, streaming, and multi-turn conversation) pinned to Cohere.
  • Featherless AI — chat completions (unary, streaming, and multi-turn conversation) pinned to Featherless AI.
  • Fireworks — chat completions (unary, streaming, and multi-turn conversation) pinned to Fireworks.
  • Groq — chat completions (unary, streaming, and multi-turn conversation) pinned to Groq.
  • Novita — chat completions (unary, streaming, and multi-turn conversation) pinned to Novita.
  • OVHcloud AI Endpoints — chat completions (unary, streaming, and multi-turn conversation) pinned to OVHcloud AI Endpoints.
  • Public AI — chat completions (unary, streaming, and multi-turn conversation) pinned to Public AI.
  • Z.ai — chat completions (unary, streaming, and multi-turn conversation) pinned to Z.ai.

Error Handling

Errors returned by client methods are one of two types in hferrors:

  • APIError — a 4xx/5xx response from the API. Carries the status code, message, response headers, method, and URL. Helpers: IsClientError(), IsServerError(), IsAuthenticationError(), IsRateLimitError(), and RetryAfter() for the server-provided retry delay.
  • SDKError — produced locally before or while decoding a response, or raised when the provider reports a failure (such as a failed remote task) inside an otherwise valid response. Carries a SDKErrorKind (validation, configuration, serialization, transport, provider, internal) and an optional wrapped error.

Use errors.As to inspect either type:

var apiErr *hferrors.APIError
if errors.As(err, &apiErr) && apiErr.IsRateLimitError() {
	// back off and retry
}

var sdkErr *hferrors.SDKError
if errors.As(err, &sdkErr) {
	log.Printf("sdk %s error: %v", sdkErr.Kind, sdkErr.Err)
}

Packages

Package Contents
hfgo Client, NewClient, and inference endpoint methods
hfopts Options, Option, and all With* helpers
hftypes Request, response, and parameter DTOs for every task
hferrors APIError, SDKError, and SDKErrorKind
hfproviders Provider interface, per-task provider interfaces, codecs, mixins
hfraw Low-level HTTP/SSE escape hatch for endpoints the SDK does not model
hfgoversion Version constant and UserAgent() helper

See docs/architecture.md for design decisions.

Providers

Requests are routed through a pluggable inference-provider layer (the hfproviders package). The default HuggingFaceProvider speaks the Hugging Face 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 Hugging Face provider. On OpenAI-compatible endpoints (e.g. chat completions), a model-string suffix chooses how the router picks a provider: a provider name (e.g. model:baseten) routes to that provider deterministically, while a routing policy (:fastest, :cheapest, :preferred) lets the router choose, with automatic failover to another provider. Without a suffix the default :fastest policy applies. See https://huggingface.co/docs/inference-providers/main/en/index.

Built-in providers have their own guides:

  • Hugging Face provider — the default; speaks the Hugging Face wire format directly.
  • Baseten provider — chat completions pinned to Baseten through the router's :baseten suffix.
  • Cerebras provider — chat completions pinned to Cerebras through the router's :cerebras suffix.
  • Cohere provider — chat completions pinned to Cohere through the router's :cohere suffix.
  • Featherless AI provider — chat completions pinned to Featherless AI through the router's :featherless-ai suffix.
  • Fireworks provider — chat completions pinned to Fireworks through the router's :fireworks-ai suffix.
  • Groq provider — chat completions pinned to Groq through the router's :groq suffix.
  • Novita provider — chat completions pinned to Novita through the router's :novita suffix.
  • OVHcloud provider — chat completions pinned to OVHcloud AI Endpoints through the router's :ovhcloud suffix.
  • Public AI provider — chat completions pinned to Public AI through the router's :publicai suffix.
  • Z.ai provider — chat completions pinned to Z.ai through the router's :zai-org suffix.
  • WaveSpeed provider — text-to-video, text-to-image, and image-to-image through WaveSpeed.
  • Fal AI provider — text-to-image, image-to-image, text-to-video, image-segmentation, and speech-recognition through Fal AI.
  • DeepInfra provider — chat completions pinned via the router's :deepinfra suffix plus speech recognition and pooled feature extraction through DeepInfra's OpenAI-compatible endpoints.
  • Together provider — chat completions pinned via the router's :together suffix, with json_schema response formats rewritten to Together's flattened shape.
  • Nscale provider — chat completions pinned via the router's :nscale suffix plus text-to-image through Nscale's OpenAI-compatible images endpoint.
  • Scaleway provider — chat completions pinned via the router's :scaleway suffix plus pooled feature extraction through Scaleway's OpenAI-compatible embeddings endpoint.
  • Replicate provider — text-to-image, image-to-image, text-to-video, and speech recognition through Replicate's asynchronous prediction API.

Advanced users who want custom providers should implement the Provider interface plus the per-task interfaces you want to support, as shown by the EchoProvider example in the hfproviders package docs. The optional HuggingFace*Mixin, WaveSpeed*Mixin, and FalAI*Mixin types exist as a convenience for reusing a built-in provider's endpoint and codec defaults: embed the ones you want (for example HuggingFaceTextClassificationMixin, WaveSpeedTextToImageMixin, FalAITextToImageMixin, or ReplicateTextToImageMixin). See docs/architecture.md.

Documentation

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a PR. Security issues should follow SECURITY.md.

Releases

See the GitHub Releases page for the release notes and published versions.

License

MIT — see LICENSE.

Additional Resources