Last updated: Nov-01-2024
This page provides an in-depth introduction to the Go SDK.
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.
- This version of the SDK supports Upload, Admin API capabilities, and generating delivery URLs.
- For details on all new features and fixes from previous versions, see the CHANGELOG.
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
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
Installation
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:
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 theapi.Bool(true)
andapi.Bool(false)
helper methods to pass the desired values. - Some parameter names have changed. Specifically:
- Instances of
Ids
in parameter names are nowIDs
. For example, thePublicIds
parameter of theDownloadZipURL
method is nowPublicIDs
. - Instances of
Url
in parameter names are nowURL
. For example,PrivateDownloadUrl
is nowPrivateDownloadURL
. - Instances of
Api
in parameter names are nowAPI
.
- Instances of
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.
Here's an example of setting the configuration parameters programmatically:
Here's an example of setting up your configuration using your API environment variable:
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:
Append additional configuration parameters, for example upload_prefix
and secure_distribution
, to the environment variable:
Complete SDK Example
- Learn more about uploading images and videos using the Go SDK.
- Check out Cloudinary's asset management capabilities, for example, renaming and deleting assets, adding tags and metadata to assets, and searching for assets.
- Stay tuned for updates with the Programmable Media Release Notes and the Cloudinary Blog.