Programmable Media


Last updated: Jun-04-2024

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

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


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.


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

2. Add configuration

Learn more: Configuration

3. Upload an image

Learn more: Image and video upload

4. Get image details

Learn more: Asset management and administration

5. Transform and deliver the image


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

Install the Cloudinary Go SDK using the go get command:


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:
  • 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.


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.

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

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

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:

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:

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

Complete SDK Example

Related topics

✔️ Feedback sent!

Rate this page: