Version-matched: these docs ship inside the module and always describe the version you have resolved. Prefer them over anything remembered from training data or found for another version.
Task documentation for the Cloudinary Go SDK. Each page is self-contained: imports, configuration, a complete runnable flow, expected results, and common failures.
Runnable versions of most tasks are in the repository's examples/ directory. They are
not part of the resolved module (see Where these docs live),
so every page carries its full flow inline.
API errors do not come back as Go error values. This is the single most important
difference between this SDK and idiomatic Go, and the mistake most likely to ship a silent
bug:
result, err := cld.Upload.Upload(ctx, file, uploader.UploadParams{})
if err != nil { /* transport / config / JSON failure only */ }
if result.Error.Message != "" { /* the API rejected the request — CHECK THIS TOO */ }err covers transport, context, and decoding failures. Anything Cloudinary itself
rejected — invalid signature, missing field, quota exceeded, asset not found — arrives with
err == nil and a populated result.Error.Message. Full detail and a reusable helper:
Handle errors.
- What this SDK does and does not do — the agent tooling to set up first (Skills, MCP servers, CLI, documentation indexes), what this module covers, and what lives elsewhere on the platform.
- Get Cloudinary credentials — no account needed: provision a cloud
with
npx @cloudinary/cloudand start building. - Import and call the SDK — module path, package names, and the
context.Contextconvention.
- Configure Cloudinary
- Upload an image
- Upload a large video — chunking is automatic
- 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 —
http.Handlerwiring, contexts, and cancellation - Handle errors
- Troubleshoot errors
There is no build step and no package manifest in Go. The module cache holds the whole repository at a version, read-only, so these files ship automatically. To find them:
go list -m -f '{{.Dir}}' github.com/cloudinary/cloudinary-go/v2
# /Users/you/go/pkg/mod/github.com/cloudinary/cloudinary-go/v2@v2.16.0Append /docs. Run it from inside a module that requires the SDK; the path contains the
resolved version, so it always matches the code you are compiling against. If the module
is not downloaded yet, run go mod download github.com/cloudinary/cloudinary-go/v2 first.
The repository's examples/ and example/ directories are nested modules with their own
go.mod, which excludes them from the parent module — so they are not in that
directory. Read them on GitHub, or clone the repository.
This is a server-side SDK. It holds your API secret, which belongs on your server only. Frontend code should receive delivery URLs or short-lived signatures generated by your server (how).
Link convention: documentation links in these docs end in .md and return raw
Markdown — the preferred format for agents and for anything that parses text. Remove the
.md suffix for the same page as browsable HTML. The repository README links the HTML
form first, since it is read by people.