Programmable Media
Menu

Go SDK

Last updated: Mar-10-2025

This page provides an in-depth introduction to the Go SDK.

Tip
If you're ready to get coding, jump straight to our quick start.

On this page:

Rate this page:

Overview

Cloudinary's Go SDK provides simple, yet comprehensive media upload and management capabilities that you can implement using code that integrates seamlessly with your existing Go application. The Go SDK also enables you to generate asset URLs, with or without transformations applied, for delivering Cloudinary assets within your application.

This guide relates to versions 2.x of Cloudinary's Go SDK. Cloudinary no longer supports versions 1.x. For breaking changes, see Update.

Related topics
This guide relates to the latest released version of the Cloudinary Go library.

Tip
Take a look at our Go sample projects to help get you started.

Architecture

The @cloudinary-go library contains all the functionality required to upload, manage, and create delivery URLs for your Cloudinary assets based on the configuration and transformation actions that you specify.

Code samples

1. Import packages

Go

// Import the required packages for upload and admin.

import (
    "context"
    "log"

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

2. Add configuration

Go
// Add your Cloudinary product environment credentials.

cld, _ := cloudinary.NewFromParams("<your-cloud-name>", "<your-api-key>", "<your-api-secret>")

Learn more: Configuration

3. Upload an image

Go
// Upload the my_picture.jpg image and set the PublicID to "my_image". 

var ctx = context.Background()
resp, err := cld.Upload.Upload(ctx, "my_picture.jpg", uploader.UploadParams{PublicID: "my_image"});

Learn more: Image and video upload

4. Get image details

Go

// Get details about the image with PublicID "my_image" and log the secure URL.

resp, err := cld.Admin.Asset(ctx, admin.AssetParams{PublicID: "my_image"});
if err != nil {
    fmt.Println("error")
}
log.Println(resp.SecureURL)

Learn more: Asset management and administration

5. Transform and deliver the image

Go
// Instantiate an object for the asset with public ID "my_image"
my_image, err := cld.Image("my_image")
if err != nil {
    fmt.Println("error")
}

// Add the transformation
my_image.Transformation = "c_fill,h_250,w_250"

// Generate and print the delivery URL
url, err := my_image.String()
if err != nil {
    fmt.Println("error")
}
log.Println(url)

Configuration and installation video tutorial

Watch this video tutorial to see how to install and configure the Go SDK:

Installation

Create a go.mod file in the directory where your Go program will be saved:

Terminal
go mod init my_folder

Install the Cloudinary Go SDK using the go get command:

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

Update

To update the Cloudinary Go SDK to the latest version, use the go get command with the -u option:

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

Migrating to versions 2.x

When migrating from versions 1.x to 2.x, note the following changes:

  • Include /v2 in the path when importing Cloudinary libraries, for example: github.com/cloudinary/cloudinary-go/v2/api/admin.
  • Parameters that were of type bool are now of type *bool and must be passed as pointers to boolean variables. You can use the api.Bool(true) and api.Bool(false) helper methods to pass the desired values.
  • Some parameter names have changed. Specifically:
    • Instances of Ids in parameter names are now IDs. For example, the PublicIds parameter of the DownloadZipURL method is now PublicIDs.
    • Instances of Url in parameter names are now URL. For example, PrivateDownloadUrl is now PrivateDownloadURL.
    • Instances of Api in parameter names are now API.

Configuration

For requests to our secure APIs (e.g., image uploads, asset management) you must have the APIKey and APISecret parameters set. You can find your product environment configuration credentials in the API Keys page of the Cloudinary Console Settings.

Setting your CloudName, APIKey and APISecret parameters can be done by initializing the Cloudinary object, or by using the CLOUDINARY_URL environment variable / system property.

Setting parameters globally

The entry point of the library is the Cloudinary struct.

Go
cld, _ := cloudinary.New()

Here's an example of setting the configuration parameters programmatically:

Go
cld, _ := cloudinary.NewFromParams("n07t21i7", "123456789012345", "abcdeghijklmnopqrstuvwxyz12")

Here's an example of setting up your configuration using your API environment variable:

Go
cld, err := cloudinary.NewFromURL("cloudinary://<api_key>:<api_secret>@<cloud_name>")

Note
You can add configuration parameters to the end of your request. For example, if you're trying to set up a custom delivery hostname (CNAME) for your assets, you should add the secure_cname parameter:
cld, err := cloudinary.NewFromURL("cloudinary://<api_key>:<api_secret>@<cloud_name>?secure_cname=my.domain.com")

Setting the CLOUDINARY_URL environment variable

You can configure the required cloud_name, api_key, and api_secret by defining the CLOUDINARY_URL environment variable. Copy the API environment variable format from the API Keys page of the Cloudinary Console Settings. Replace <your_api_key> and <your_api_secret> with your actual values, while your cloud name is already correctly included in the format. When using Cloudinary through a PaaS add-on (e.g., Heroku or AppFog), this environment variable is automatically defined in your deployment environment. For example:

CLOUDINARY_URL=cloudinary://my_key:my_secret@my_cloud_name

Append additional configuration parameters, for example upload_prefix and secure_distribution, to the environment variable:

CLOUDINARY_URL=cloudinary://my_key:my_secret@my_cloud_name?secure_distribution=mydomain.com&upload_prefix=myprefix.com

Complete SDK Example

Go
package main

import (
    "context"
    "log"

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

func main() {
    // Start by creating a new instance of Cloudinary using CLOUDINARY_URL environment variable.
    // Alternatively you can use cloudinary.NewFromParams() or cloudinary.NewFromURL().
    var cld, err = cloudinary.New()
    if err != nil {
        log.Fatalf("Failed to initialize Cloudinary, %v", err)
    }
    var ctx = context.Background()
    // Upload an image to your Cloudinary product environment from a specified URL.
    //
    // Alternatively you can provide a path to a local file on your filesystem,
    // base64 encoded string, io.Reader and more.
    //
    // For additional information see:
    // https://cloudinary.com/documentation/upload_images
    //
    // Upload can be greatly customized by specifying uploader.UploadParams,
    // in this case we set the Public ID of the uploaded asset to "logo".
    uploadResult, err := cld.Upload.Upload(
        ctx,
        "https://res.cloudinary.com/demo/image/upload/v1598276026/docs/models.jpg",
        uploader.UploadParams{PublicID: "models",
            UniqueFilename: api.Bool(false),
            Overwrite:      api.Bool(true)})
    if err != nil {
        log.Fatalf("Failed to upload file, %v\n", err)
    }
    log.Println(uploadResult.SecureURL)
    // Prints something like:
    // https://res.cloudinary.com/<your cloud name>/image/upload/v1615875158/models.png
    // uploadResult contains useful information about the asset, like Width, Height, Format, etc.
    // See uploader.UploadResult struct for more details.
    // Now we can use Admin API to see the details about the asset.
    // The request can be customised by providing AssetParams.
    asset, err := cld.Admin.Asset(ctx, admin.AssetParams{PublicID: "models"})
    if err != nil {
        log.Fatalf("Failed to get asset details, %v\n", err)
    }
    // Print some basic information about the asset.
    log.Printf("Public ID: %v, URL: %v\n", asset.PublicID, asset.SecureURL)
    // Cloudinary also provides a very flexible Search API for filtering and retrieving
    // information on all the assets in your product environment with the help of query expressions
    // in a Lucene-like query language.
    searchQuery := search.Query{
        Expression: "resource_type:image AND uploaded_at>1d AND bytes<1m",
        SortBy:     []search.SortByField{{"created_at": search.Descending}},
        MaxResults: 30,
    }
    searchResult, err := cld.Admin.Search(ctx, searchQuery)
    if err != nil {
        log.Fatalf("Failed to search for assets, %v\n", err)
    }
    log.Printf("Assets found: %v\n", searchResult.TotalCount)
    for _, asset := range searchResult.Assets {
        log.Printf("Public ID: %v, URL: %v\n", asset.PublicID, asset.SecureURL)
    }
}

Sample projects

Take a look at the Go sample projects page to help you get started integrating Cloudinary into your Go application.

Tip
Check out our collection of Go code explorers too!

Related topics

✔️ Feedback sent!