cloudinary

Cloudinary Go SDK

Upload, transform, optimize, and manage images and videos with Cloudinary from Go — the cloudinary-go module.

Install

go get github.com/cloudinary/cloudinary-go/v2

Quick start

Set your API environment variable (Console > Settings > API Keys):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

Upload an image and get an optimized delivery URL:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/cloudinary/cloudinary-go/v2"
	"github.com/cloudinary/cloudinary-go/v2/api/uploader"
)

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, "Quick start failed:", err)
		fmt.Fprintln(os.Stderr, "Check that CLOUDINARY_URL is set (Console > Settings > API Keys).")
		os.Exit(1)
	}
}

func run() error {
	cld, err := cloudinary.New()
	if err != nil {
		return err
	}
	ctx := context.Background()

	// Upload a remote image (a local file path works the same way).
	result, err := cld.Upload.Upload(ctx,
		"https://res.cloudinary.com/demo/image/upload/sample.jpg",
		uploader.UploadParams{PublicID: "quickstart-sample"})
	if err != nil {
		return err
	}
	if result.Error.Message != "" {
		// Cloudinary rejected the request; this arrives with err == nil.
		return fmt.Errorf("upload rejected: %s", result.Error.Message)
	}
	fmt.Println("Uploaded:", result.PublicID)

	// Build a 400x400 auto-cropped URL with automatic format and quality.
	image, err := cld.Image(result.PublicID)
	if err != nil {
		return err
	}
	image.Transformation = "c_fill,g_auto,h_400,w_400/f_auto,q_auto"
	url, err := image.String()
	if err != nil {
		return err
	}
	fmt.Println("Optimized URL:", url)
	return nil
}

Save as quickstart.go and run go run quickstart.go. Create a free account if you don't have one — or run npx @cloudinary/cloud to provision one without signing up.

Note the two checks in run: err reports transport, context, and decoding failures, while a Cloudinary rejection arrives with err == nil and a populated result.Error.Message. See Handle errors.

Common tasks

• Get Cloudinary credentials
• Import and call the SDK
• Configure Cloudinary
• Upload an image
• Upload a large video
• Sign a browser upload
• Transform and deliver an image
• Transform and deliver a video
• Search and manage assets
• Moderate an upload
• Use structured metadata
• Serve uploads over HTTP
• Handle errors
• Troubleshoot errors

Runnable versions live in examples/ — each is a complete program you can run directly. It is a nested module, so run them from inside examples/.

When to use this SDK

Use this module in Go server-side code: uploads, signed operations, asset administration, search, moderation, and delivery URL generation.

For other jobs, better-fitting tools exist:

• Browser or frontend framework rendering: the frontend SDKs (md) — this module generates URLs, not markup.
• Complete in-browser upload UI: Upload Widget (md), signed from Go with Sign a browser upload.
• Video playback UI: Cloudinary Video Player (md).
• Text-to-image generation and image-to-video: platform APIs (md), not wrapped by this module.
• Account and sub-account provisioning: Provisioning API (md) over HTTP.
• Multi-step media workflow automation: MediaFlows (md).
• Interactive agent-driven asset operations: Cloudinary MCP servers and Skills (md).

The full capability map — plus the Skills, MCP servers, and CLI worth setting up first — is in docs/platform-capabilities.md.

Status and compatibility

Stable, actively maintained. See CHANGELOG.md.

Documentation

• Bundled task docs — ship inside the module, version-matched.
• Go SDK guide — the full documentation (md).
• Logging — redefining the logger and adjusting the log level.

Documentation links in this README point at the browsable HTML page, with an (md) companion link that returns the same page as raw Markdown. Inside docs/ and examples/ the links are Markdown-only, since those files are written to be read by coding agents. Either form works for any page: add .md for Markdown, drop it for HTML.

For AI coding agents

• Contributing to this repo: read AGENTS.md.
• Using the installed module: the docs bundled in the module match your resolved version and are the source of truth; start with platform-capabilities before assuming a feature exists.

Go has no fixed install path, so locate the bundled docs with:

go list -m -f '{{.Dir}}' github.com/cloudinary/cloudinary-go/v2
# then read <that path>/docs/README.md

Support

• SDK bugs and feature requests: GitHub issues
• Account and platform questions: Cloudinary support

Contributing: see CONTRIBUTING.md.

Security

See SECURITY.md for private vulnerability reporting. Keep your api_secret in server-side code; for client uploads, use the server-signed pattern in Sign a browser upload.

License

Released under the MIT license — see LICENSE. Copyright (c) Cloudinary Ltd.