Golang API client for Uploadcare

Uploadcare Golang API client that handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.

• Requirements
• Installation
• Configuration
• Usage
• Useful links

Requirements

Go 1.25

Installation

Install uploadcare-go with:

go get -u -v github.com/uploadcare/uploadcare-go/v2/...

Then import it using:

import (
	"github.com/uploadcare/uploadcare-go/v2/ucare"
	"github.com/uploadcare/uploadcare-go/v2/file"
	"github.com/uploadcare/uploadcare-go/v2/group"
	"github.com/uploadcare/uploadcare-go/v2/upload"
	"github.com/uploadcare/uploadcare-go/v2/conversion"
	"github.com/uploadcare/uploadcare-go/v2/metadata"
	"github.com/uploadcare/uploadcare-go/v2/addon"
	"github.com/uploadcare/uploadcare-go/v2/projectapi"
)

Configuration

REST & Upload API client

creds := ucare.APICreds{
	SecretKey: "your-project-secret-key",
	PublicKey: "your-project-public-key",
}

conf, err := ucare.NewConfig(creds, ucare.WithSignBasedAuthentication())
if err != nil {
	log.Fatalf("creating uploadcare API config: %s", err)
}

client, err := ucare.NewClient(creds, conf)
if err != nil {
	log.Fatalf("creating uploadcare API client: %s", err)
}

NewConfig accepts additional options:

conf, err := ucare.NewConfig(creds,
	ucare.WithSignBasedAuthentication(),
	ucare.WithUserAgent("my-app/1.0.0"),                  // appended to the default User-Agent
	ucare.WithRetry(&ucare.RetryConfig{MaxRetries: 3}),   // retry throttled (429) requests; off by default
	ucare.WithCDNBase("https://cdn.example.com"),         // override the per-project CDN domain
)

By default the CDN base URL is derived automatically from the public key, and URLs returned by the API (file.Info.OriginalFileURL, group.Info.CDNLink, upload.GroupInfo.CDNLink) are rewritten to point at it.

Project API client

The Project API uses bearer token authentication. Tokens can be obtained via Uploadcare Support.

conf := ucare.NewBearerConfig()
client, err := ucare.NewBearerClient("your-bearer-token", conf)
if err != nil {
	log.Fatalf("creating project API client: %s", err)
}

projectSvc := projectapi.NewService(client)

Usage

For a comprehensive list of examples, check out the API documentation. Below are a few usage examples:

Getting a list of files:

fileSvc := file.NewService(client)

listParams := file.ListParams{
	Stored:  ucare.Bool(true),
	OrderBy: ucare.String(file.OrderByUploadedAtDesc),
}

fileList, err := fileSvc.List(context.Background(), listParams)
if err != nil {
	// handle error
}

// getting IDs of the files
ids := make([]string, 0, 100)
for fileList.Next() {
	finfo, err :=  fileList.ReadResult()
	if err != nil {
		// handle error
	}

	ids = append(ids, finfo.ID)
}

Acquiring file-specific info:

fileID := ids[0]
file, err := fileSvc.Info(context.Background(), fileID, nil)
if err != nil {
	// handle error
}

if file.IsImage && file.ContentInfo != nil && file.ContentInfo.Image != nil {
	h := file.ContentInfo.Image.Height
	w := file.ContentInfo.Image.Width
	fmt.Printf("image size: %dx%d\n", h, w)
}

Uploading a file:

f, err := os.Open("file.png")
if err != nil {
	// handle error
}

uploadSvc := upload.NewService(client)

params := upload.FileParams{
	Data:        f,
	Name:        f.Name(),
	ContentType: "image/png",
}
fID, err := uploadSvc.File(context.Background(), params)
if err != nil {
	// handle error
}

Upload picks between direct and multipart uploads automatically based on file size (multipart above 10MB by default) and accepts custom metadata:

f, err := os.Open("large-video.mp4")
if err != nil {
	// handle error
}

info, err := uploadSvc.Upload(context.Background(), upload.UploadParams{
	Data:        f,
	Name:        f.Name(),
	ContentType: "video/mp4", // required for the multipart path (files > 10MB)
	Metadata:    map[string]string{"source": "import"},
})
if err != nil {
	// handle error
}

Working with per-file metadata:

metaSvc := metadata.NewService(client)

_, err := metaSvc.Set(context.Background(), fileID, "source", "import")
if err != nil {
	// handle error
}

all, err := metaSvc.List(context.Background(), fileID)
if err != nil {
	// handle error
}
fmt.Printf("metadata: %v\n", all)

Executing an add-on (e.g. background removal) and polling for the result:

addonSvc := addon.NewService(client)

exec, err := addonSvc.Execute(context.Background(), addon.AddonRemoveBG, addon.ExecuteParams{
	Target: fileID,
})
if err != nil {
	// handle error
}

status, err := addonSvc.Status(context.Background(), addon.AddonRemoveBG, exec.RequestID)
if err != nil {
	// handle error
}
fmt.Printf("addon status: %s\n", status.Status)

Managing projects via the Project API:

conf := ucare.NewBearerConfig()
client, err := ucare.NewBearerClient("your-bearer-token", conf)
if err != nil {
	log.Fatalf("creating project API client: %s", err)
}

projectSvc := projectapi.NewService(client)

projects, err := projectSvc.List(context.Background(), nil)
if err != nil {
	log.Fatalf("listing projects: %s", err)
}
if !projects.Next() {
	log.Fatal("no projects found")
}
firstProject, err := projects.ReadResult()
if err != nil {
	log.Fatalf("reading first project: %s", err)
}

proj, err := projectSvc.Get(context.Background(), firstProject.PubKey)
if err != nil {
	log.Fatalf("getting project: %s", err)
}
fmt.Printf("project: %s (%s)\n", proj.Name, proj.PubKey)

usage, err := projectSvc.GetUsage(context.Background(), proj.PubKey, projectapi.UsageDateRange{
	From: "2025-01-01",
	To:   "2025-01-31",
})
if err != nil {
	log.Fatalf("getting usage: %s", err)
}
fmt.Printf("usage days: %d\n", len(usage.Data))

Useful links

Golang API client documentation
Uploadcare documentation
Upload API reference
REST API reference Changelog
Contributing guide
Security policy
Support