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.
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 & MediaREADME.md
Originalhfgo
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_TOKENenvironment 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.
- Chat
- Feature Extraction
- Fill Mask
- Image Classification
- Image Segmentation
- Object Detection
- Question Answering
- Speech Recognition
- Summarization
- Table Question Answering
- Text Classification
- Text to Image
- Token Classification
- Translation
- Zero-Shot Text Classification
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(), andRetryAfter()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 aSDKErrorKind(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
:basetensuffix. - Cerebras provider — chat completions pinned to
Cerebras through the router's
:cerebrassuffix. - Cohere provider — chat completions pinned to
Cohere through the router's
:coheresuffix. - Featherless AI provider — chat
completions pinned to Featherless AI through the router's
:featherless-aisuffix. - Fireworks provider — chat completions
pinned to Fireworks through the router's
:fireworks-aisuffix. - Groq provider — chat completions pinned to
Groq through the router's
:groqsuffix. - Novita provider — chat completions pinned to
Novita through the router's
:novitasuffix. - OVHcloud provider — chat completions pinned
to OVHcloud AI Endpoints through the router's
:ovhcloudsuffix. - Public AI provider — chat completions pinned
to Public AI through the router's
:publicaisuffix. - Z.ai provider — chat completions pinned to
Z.ai through the router's
:zai-orgsuffix. - 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
:deepinfrasuffix plus speech recognition and pooled feature extraction through DeepInfra's OpenAI-compatible endpoints. - Together provider — chat completions pinned
via the router's
:togethersuffix, withjson_schemaresponse formats rewritten to Together's flattened shape. - Nscale provider — chat completions pinned via
the router's
:nscalesuffix plus text-to-image through Nscale's OpenAI-compatible images endpoint. - Scaleway provider — chat completions
pinned via the router's
:scalewaysuffix 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
- API reference — full godoc.
- examples/ — runnable programs for every task and variant.
- docs/ — documentation index, including architecture, release process, the Bruno API collection, and provider guides under docs/providers.
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.