Go SDK

The Cloudinary Go SDK provides simple, yet comprehensive image and video upload, transformation, optimization, and delivery capabilities through the Cloudinary APIs, that you can implement using code that integrates seamlessly with your existing Go application.

How would you like to learn?

Install

Cloudinary's Go integration library is available as an open-source package.

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

To install the library, run:

Update

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

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.

Configure

Import the required packages for upload and admin:

Set required configuration parameters

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.

To define the CLOUDINARY_URL environment variable:

1. Copy the API environment variable format from the API Keys page of the Cloudinary Console Settings.
2. Replace <api_key> and <api_secret> with your actual values. Your cloud name is already correctly included in the format.

For example:

The entry point of the library is the Cloudinary struct. Here's an example of setting up your configuration using your API environment variable:

Alternatively, you can pass your CloudName, APIKey and APISecret as parameters:

Or initialize a new Cloudinary instance (if you've already set the environment variable):

Set additional configuration parameters

In addition to the required configuration parameters, you can define a number of optional configuration parameters if relevant.

You can append configuration parameters, for example upload_prefix and secure_distribution, to the environment variable:

Or use the NewFromURL method:

Or you can set them by accessing the Config struct fields (using PascalCase field names):

Configuration video tutorial

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

Use

Once you've installed and configured the Go SDK, you can use it for:

• Uploading files to your product environment: You can upload any files, not only images and videos, set your own naming conventions and overwrite policies, moderate and tag your assets on upload, and much more. See example
• Transforming and optimizing images and videos: Keeping your original assets intact in your product environment, you can deliver different versions of your media - different sizes, formats, with effects and overlays, customized for your needs. See example
• Managing assets: Using methods from the Admin and Upload APIs, you can organize your assets, for example, list, rename and delete them, add tags and metadata and use advanced search capabilities. See example

Quick example: File upload

The following Go code uploads the dog.mp4 video using the PublicID, my_dog. The video overwrites the existing my_dog video if it exists. When the video upload finishes, the specified notification URL receives details about the uploaded media asset.

Quick example: Transform and optimize

Take a look at the following transformation code and the image it delivers:

In the Go SDK, transformations are applied by passing the transformation string directly to the Transformation parameter. The transformation string uses the same syntax as the Transformation URL API, with individual transformations separated by commas and transformation chains separated by forward slashes.

This relatively simple transformation string performs all of the following on the original front_face.jpg image before delivering it:

• Crop to a 150x150 thumbnail using face-detection gravity to automatically determine the location for the crop
• Round the corners with a 20 pixel radius
• Apply a sepia effect
• Overlay the Cloudinary logo on the southeast corner of the image (with a slight offset). Scale the logo overlay down to a 50 pixel width, with increased brightness and partial transparency (opacity = 60%).
• Rotate the resulting image (including the overlay) by 10 degrees
• Optimize the image to reduce the size of the image without impacting visual quality.
• Convert and deliver the image in PNG format (the originally uploaded image was a JPG)

And here's the URL that's generated:

In a similar way, you can transform a video.

Quick example: Get details of a single asset

The following Go example uses the Admin API Asset method to return details of the image with PublicID cld-sample:

Sample output:

Sample projects

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