HFS

HFS is a lightweight Go client for interacting with Hugging Face Spaces that expose Gradio-style APIs.

It simplifies this workflow by providing a single .Do() method that:

1. Sends your inputs
2. Retrieves the event ID
3. Fetches the final result stream
4. Returns typed output

---

✨ Features

• 🌐 Connect to any Hugging Face Spaces endpoint
• 🔁 Handles event ID + result fetching
• 🔐 Supports custom headers and bearer tokens
• ⚙️ Generic over input and output types
• 🧩 FileData support for inputs and outputs
• 🧼 Minimal API — just call .Do()
• 🛡️ No dependencies outside the standard library

---

Installation

go get github.com/ucukertz/hfs

---

Simple Usage Example

package main

import (
    "fmt"
    "github.com/ucukertz/hfs"
)

func main() {
    space := hfs.NewHfs[string, string]("your-space-name").
        WithBearerToken("your-hf-token")

    result, err := space.Do("/your-endpoint", "your-input-string")
    if err != nil {
        panic(err)
    }

    for _, item := range result {
        fmt.Println(item)
    }
}

---

Using any for Mixed Input/Output Types

package main

import (
    "fmt"
    "github.com/ucukertz/hfs"
)

func main() {
    space := hfs.NewHfs[any, any]("your-space-name").
        WithBearerToken("your-hf-token")

    output, err := space.Do(
        "/your-endpoint",
        "some text",
        123,
        true,
        4.5,
        map[string]any{"key": "value"},
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(output)
}

---

Using FileData as Hugging Face Spaces Input

package main

import (
    "fmt"
    "github.com/ucukertz/hfs"
)

func main() {
    fileInput, err := hfs.NewFileData("input.jpg").
        FromUrl("https://example.com/image.jpg")
    if err != nil {
        panic(err)
    }

    space := hfs.NewHfs[any, any]("your-space-name").
        WithBearerToken("your-hf-token")

    output, err := space.Do(
        "/your-endpoint",
        fileInput,
        "your-prompt",
        42,
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(output)
}

---

Handling FileData Output

package main

import (
    "os"
    "github.com/ucukertz/hfs"
)

func main() {
    space := hfs.NewHfs[any, any]("your-space-name").
        WithBearerToken("your-hf-token")

    out, err := space.Do("/your-endpoint", "your-input")
    if err != nil {
        panic(err)
    }

    bytes, err := hfs.GetFileData(out[0])
    if err != nil {
        panic(err)
    }

    os.WriteFile("output.png", bytes, 0644)
}

You can use DoFD() instead of Do() when you only want to use []byte from an output FileData and the FileData is the first item of the output.

---

Notes

• GetFileData() automatically extracts and downloads the content of a FileData output.
• Use FileData.FromUrl(), .FromBytes(), .FromUpload(), or .FromBase64() to construct file inputs. Some spaces demand files used as input to be uploaded directly to the server, only FileData created with .FromUpload() work on those.
• .WithBearerToken(), .WithTimeout(), .WithUserAgent(), and .WithHTTPClient() allow full customization.
• NewHfsRaw() can be used for spaces not hosted on Hugging Face.

---

License

Distributed under the MIT License. See LICENSE for more information.

Author

Created by ucukertz.