Programmable Media
Menu

Ruby/Rails quick start

Last updated: Jun-04-2024

This quick start lets you get an end-to-end implementation up and running using the Ruby/Rails SDK in 5 minutes or less.

On this page:

Rate this page:

1. Set up and configure the SDK

Install the SDK

In a terminal, in your Ruby environment, run:

Ruby
gem install cloudinary

Configure Cloudinary

In your project, create a new file called config.rb with the code below. Make sure to update it to use your product environment's credentials:

config.rb
Ruby
# Replace the 'config_from_url' string value below with your
# product environment's credentials, available from your Cloudinary console.
# =====================================================

require 'cloudinary'

Cloudinary.config_from_url("cloudinary://API_KEY:API_SECRET@CLOUD_NAME")

Important
When writing your own applications, follow your organization's policy on storing secrets and don't expose your API secret.

Reference the configuration from a ruby script

In your project, create a new file called quickstart.rb.

For the sake of this quick start, you'll put all the Cloudinary code other than the configuration in this single file and only run it at the end.

To reference your product environment configuration from this new file, add:

quickstart.rb
Ruby
require 'cloudinary'

if Cloudinary.config.api_key.blank?
  require './config'
end

puts 'My cloud name is:' + Cloudinary.config.cloud_name

2. Upload files

To upload some remote files to Cloudinary, paste the following to the end of your quickstart.rb file:

quickstart.rb (continued)
Ruby
## Upload two files using the Upload API:

# Use the uploaded filename as the asset's public ID + allow overwriting the asset with new versions.
upload1=Cloudinary::Uploader.upload("https://cloudinary-devs.github.io/cld-docs-assets/assets/images/model.jpg", 
    use_filename:true, 
    unique_filename:false,
    overwrite:true
    )

# Retrieve some attributes from the first upload response.

  puts "File size of the #{upload1['public_id']}.#{upload1['format']} #{upload1['resource_type']}: #{upload1['bytes']/1024} KB"     

# Manually set the asset's public ID + allow overwriting asset with new versions.

  upload2=Cloudinary::Uploader.upload("https://cloudinary-devs.github.io/cld-docs-assets/assets/images/coffee_cup.jpg", 
      public_id: "coffee", 
      unique_filename: false,
      overwrite: true
      )


# Retrieve some attributes from the second upload response.
  puts "File size of the #{upload2['public_id']}.#{upload2['format']} #{upload2['resource_type']}: #{upload2['bytes']/1024} KB"

3. Get and use details of an image

Paste these two snippets to perform some management operations on the assets you previously uploaded:

Return details of an existing resource

quickstart.rb (continued)
Ruby
## Manage existing assets using the Admin API

# Retrieve and print the details for a specific stored asset, 
# including the optional `faces` data, 
# based on the public ID returned in the previous upload.

my_asset = upload1['public_id']

puts %{
Asset details:
=================

}

jj details = Cloudinary::Api.resource(my_asset,
faces: true)

puts %{
================================

}

Retrieve and update specific attributes of an asset

quickstart.rb (continued)
Ruby
# Find out how many faces are in the image, and depending on result, tag the image accordingly.
facecount = details['faces'].count

puts "Number of faces in this image: #{facecount}"  

if facecount > 0
  asset_update=Cloudinary::Api.update(my_asset,
  tags: "people")
else 
  asset_update=Cloudinary::Api.update(my_asset,
  tags: "products")
end

asset_tags = asset_update['tags']

puts "Asset tags: #{asset_tags}"

4. Transform images

Add this code to your file in order to generate a few different transformation URLs on the two assets you previously uploaded:

quickstart.rb (continued)
Ruby
## Generate transformation URLs for previously uploaded assets.

my_asset1 = upload1['public_id']+'.jpg'
my_asset2 = upload2['public_id']+'.jpg'

# Scale and then crop the excess to 'fill' 640*200px banner-shape, focussed on the largest face (if any). 
puts Cloudinary::Utils.cloudinary_url(my_asset1, transformation: 
    {crop: "fill", gravity: "face", width: 640, height: 200,  }
  )

# Create a 200px square (1:1 aspect ratio) thumbnail, then round to a circle to get a profile photo of the face.
puts Cloudinary::Utils.cloudinary_url(my_asset1, transformation: [
    {crop: "thumb", gravity: "face",width: 200, aspect_ratio: "1.0"},
    {radius: "max"}
])

# Deliver a URL link to the original of the second image.
puts Cloudinary::Utils.cloudinary_url(my_asset2)

# Scale & crop to a portrait image (6:10 aspect ratio), apply a sepia effect, 
# and automatically optimize the image quality and file format to best balance 
# between visual quality and small file size.
puts Cloudinary::Utils.cloudinary_url(my_asset2, transformation: [
    {crop: "fill", aspect_ratio: "0.6", width: 400},
    {effect: "sepia"},
    {fetch_format: "auto"},
    {quality: "auto"}
    ])

5. Run your code

In your Ruby IDE or in a terminal (from the /scripts folder of your project), run your quickstart.rb script and take a look at the output you get from each step of this quick start:

Ruby
ruby quickstart.rb

View the completed code

You can find the full code example for this quick start on GitHub.

Next steps

  • Learn more about the Ruby/Rails SDK by visiting the other pages in this SDK guide.
  • Get comprehensive details about Cloudinary features and capabilities:
Cloudinary Academy

 

Check out our Introduction to Cloudinary for Ruby Developers course in the Cloudinary Academy. This self-paced resource provides video-based lessons, sample scripts and other learning material to get you going with Ruby and Cloudinary today.

✔️ Feedback sent!