Flag of Ukraine

Heroku Addon Heroku Addon

To use Transloadit with Heroku, add our Addon via their web interface or the the Heroku CLI like so:

# yarn global add heroku
# heroku create your-sample-app-123
$ heroku addons:create transloadit --app=your-sample-app-123
-----> Adding transloadit to your-sample-app-123... done, v18 (free)

Once Transloadit has been added the TRANSLOADIT_AUTH_KEY and TRANSLOADIT_SECRET_KEY settings will be available in the app configuration and will contain the credentials needed to authenticate to the Transloadit API. This can be confirmed using the heroku config:get command.

$ heroku config:get TRANSLOADIT_AUTH_KEY

Now you're ready to start using Transloadit in your Heroku app using an SDK for any programming language that Heroku supports.

When you're ready to use a paid plan, you can upgrade like so:

$ heroku addons:upgrade transloadit:enterprise
-----> Upgrading transloadit:enterprise to your-sample-app-123... done, v18 ($299/mo)
       Your plan has been updated to: transloadit:enterprise

Note that Heroku does not support overages, meaning the service will stop when you reach your plan limit.


Warning! Heroku does not support overage in their billing and so we had to disable that on our end to be compatible with the platform without going bankrupt. This could result in stopping the service for you if you don't upgrade in time! If you'd rather enable overage, consider signing up for Transloadit directly.

Transloadit can be attached to a Heroku application via the CLI:

$ heroku addons:add transloadit
-----> Adding transloadit to sharp-mountain-4005... done, v18 (free)
A list of all plans available can be found here.

Once Transloadit has been added the TRANSLOADIT_AUTH_KEY and TRANSLOADIT_SECRET_KEY settings will be available in the app configuration and will contain the credentials needed to authenticate to the Transloadit API. This can be confirmed using the heroku config:get command.

$ heroku config:get TRANSLOADIT_AUTH_KEY


With your TRANSLOADIT_AUTH_KEY and TRANSLOADIT_SECRET_KEY in place you can now integrate it with any of our SDKs corresponding to your project. Here's a list of our SDKs:

Using with Ruby (Uses our Ruby SDK)

Verify that the TRANSLOADIT_AUTH_KEY and TRANSLOADIT_SECRET_KEY variables are set.

Ruby applications need to add the following entry into their Gemfile specifying the Transloadit client library.

gem 'transloadit'

Then update application dependencies with bundler.

$ bundle install

Finally re-deploy your application.

$ git add .
$ git commit -a -m "add transloadit instrumentation"
$ git push heroku main

First encoding job

After installing the transloadit Gem and deploying your app you can start talking to the Transloadit API:

require 'transloadit'

puts "Resizing lolcat.jpg on #{ENV['TRANSLOADIT_URL']}"

transloadit = Transloadit.new(
  :service => ENV['TRANSLOADIT_URL'],
  :key     => ENV['TRANSLOADIT_AUTH_KEY'],

resize = transloadit.step 'resize', '/image/resize',
  :width  => 320,
  :height => 240

assembly = transloadit.assembly(
  :steps => [ resize ]

response = assembly.submit! open('lolcat.jpg')

# loop until processing is finished
until response.finished?
  sleep 1; response.reload! # you'll want to implement a timeout in your production app

if response.error?
 # handle error
 # handle other cases

Using with Ruby on Rails (Uses our Rails SDK)

Here we'll show how to use Transloadit in a freshly setup Rails project and Heroku app.

If you haven't already done so, go ahead and install Rails.

$ gem install rdoc rails

With Rails installed, let's create a new app called 'transloku'.

$ rails new transloku
$ cd transloku

In order to use Transloadit in this app, we need to add the Gem to our Gemfile and bundle things up.

Remove sqlite3 from your Gemfile

$ echo "ruby '2.0.0'" >> Gemfile
$ echo "gem 'transloadit-rails'" >> Gemfile
$ echo "gem 'pg'" >> Gemfile
$ bundle install

With that in place, it's time to generate our Transloadit configuration, as well as a basic UploadsController and a dummy Upload model.

$ rails g transloadit:install
$ rails g controller uploads new create
$ rails g model upload
$ rake db:migrate

The controller generator we just executed has probably put two GET routes into your config/routes.rb. We don't want those, so let's go ahead and overwrite them with this.

Transloku::Application.routes.draw do
  resources :uploads

Next we need to configure our config/transloadit.yml file. For this tutorial, just put in your credentials, and define an image resize step as indicated below:

  secret: <%= ENV['TRANSLOADIT_SECRET_KEY'] %>

        robot: '/image/resize'
        format: 'jpg'
        width: 320
        height: 200

Note that we encourage you to enable authentication in your Transloadit Account and put your secret into the config/transloadit.yml to have your requests signed.

Make your config/database.yml look like this:

  adapter: postgresql
  encoding: unicode
  database: transloku_development
  pool: 5

  adapter: postgresql
  encoding: unicode
  database: transloku_test
  pool: 5

  adapter: postgresql
  encoding: unicode
  database: transloku_production
  pool: 5

Alright, time to create our upload form. In order to do that, please open app/views/uploads/new.html.erb, and put the following code in:

<%= javascript_include_tag '//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js' %>

<h1>Upload an image</h1>
<%= form_for Upload.new, :html => { :id => 'upload' } do |form| %> <%= transloadit :image_resize %>
<%= form.label :file, 'File to upload' %> <%= form.file_field :file %> <%= form.submit %> <% end %>
<%= transloadit_jquerify :upload, :wait => true %>

With this in place, we can modify the app/views/uploads/create.html.erb view to render the uploaded and resized image:

<h1>Resized upload image</h1>
<%= image_tag params[:transloadit][:results][:resize].first[:url] %>

In order to use the transloadit params in your controller and views you have to include the ParamsDecoder into your controller. Let's do that for our UploadsController.

Open up app/controllers/uploads_controller.rb and adapt it like that:

class UploadsController < ApplicationController
  include Transloadit::Rails::ParamsDecoder

  def new

  def create

That's it. If you've followed the steps closely, you should now be able to try your first upload. Don't forget to start your rails server first:

$ rails server

Then go to http://localhost:3000/uploads/new, and upload an image. If you did everything right, you should see the uploaded and resized file as soon as the upload finishes.

All looking sharp? Let's publish this to Heroku

$ git init
$ git add .
$ git commit -m "init"
$ heroku login
$ heroku create
$ heroku addons:add transloadit
$ heroku config:get TRANSLOADIT_AUTH_KEY
$ git push heroku main
$ heroku run rake db:migrate
$ heroku open && heroku logs --tail

Point your browser to /uploads/new

Using with any Language

Instead of talking server-to-server, your website visitors can directly upload to Transloadit's specialized upload servers, so in theory there's no need for server-side languages.

The easiest way to accomplish this would be to to include our jQuery SDK in your HTML.

It includes a Twitter Bootstrap compatible progress bar, and it saves you development time having to handle the file uploads yourself, and then pushing it to our API.

<script type="text/javascript">
  // We call .transloadit() after the DOM is initialized:
  $(function () {

Alternatively, check our Uppy, our next-gen file uploader for the web.


See GitHub for the full documentation.

Related blog posts

20% off any plan for the Uppy community
Use the UPPY20 code when upgrading.
Sign up
20% off any plan for the tus community
Use the TUS20 code when upgrading.
Sign up
Product Hunt
20% off any plan for Product Hunters
Use the PRH20 code when upgrading.
Sign up