Render mockups with Ruby on Rails

SudoMock turns a Photoshop template into a finished image over HTTPS, so a Rails app needs nothing past net/http and json from the standard library. This page puts that behind a service object, a rake task and one controller action.

Add SudoMock rendering to a Ruby on Rails app.

Open in Cursor

Prerequisites

An API key. Create one and keep the sm_ value. It travels in the x-api-key header.
A Rails app with encrypted credentials in use, or SUDOMOCK_API_KEY set in the environment.
A PSD holding at least one visible smart object, reachable at a public URL. Preparing a PSD covers what the file needs.
Artwork served over HTTPS, or held in memory as base64.

Guide

Store the key

Credentials keep the key out of the repository and out of the log.

bin/rails credentials:edit

sudomock:
  api_key: sm_your_api_key

Confirm the key is live before you write a line of client code:

curl "https://api.sudomock.com/api/v1/me" \
  -H "x-api-key: sm_your_api_key"

Add a client

One small service object carries the header, the timeout and the failure. Everything below calls it.

app/services/sudomock.rb

require "net/http"
require "json"

module Sudomock
  BASE = "https://api.sudomock.com"

  class Error < StandardError
    attr_reader :status, :code

    def initialize(status, body)
      @status = status
      @code = body["error_code"]
      super(body["message"] || body["detail"] || "Request failed")
    end
  end

  def self.api_key
    Rails.application.credentials.dig(:sudomock, :api_key) ||
      ENV.fetch("SUDOMOCK_API_KEY")
  end

  def self.post(path, payload)
    uri = URI("#{BASE}#{path}")
    request = Net::HTTP::Post.new(uri)
    request["x-api-key"] = api_key
    request["Content-Type"] = "application/json"
    request.body = JSON.generate(payload)

    response = Net::HTTP.start(
      uri.host, uri.port, use_ssl: true, read_timeout: 120
    ) { |http| http.request(request) }

    body = JSON.parse(response.body)
    return body if response.is_a?(Net::HTTPSuccess)

    raise Error.new(response.code.to_i, body)
  end
end

A failed call still returns a JSON body, and error_code is what you branch on. Errors lists the values and says which ones are worth retrying.

Upload the template once

Uploading registers the PSD and names every slot inside it. This belongs in a rake task, not in a request.

lib/tasks/sudomock.rake

namespace :sudomock do
  desc "Register a PSD template and print its UUIDs"
  task :upload, [:url, :name] => :environment do |_task, args|
    result = Sudomock.post("/api/v1/psd/upload", {
      psd_file_url: args[:url],
      psd_name: args[:name]
    })

    data = result["data"]
    puts "mockup_uuid: #{data['uuid']}"
    data["smart_objects"].each do |object|
      puts "  #{object['name']}: #{object['uuid']}"
    end
  end
end

bin/rails "sudomock:upload[https://example.com/tee.psd,Tee front]"

Keep the printed values. The mockup UUID and the smart object UUID stay valid for every later render, so they belong in credentials, in the environment, or on the product row they describe.

A product photo can stand in for a PSD. Create it with POST /api/v1/photo-mockups and render it with POST /api/v1/photo-mockups/{mockup_id}/render. See Photo mockups.

Render from a controller

The render call takes the two UUIDs and the artwork, and answers with the finished file.

config/routes.rb

post "mockups/render", to: "mockups#create"

app/controllers/mockups_controller.rb

class MockupsController < ApplicationController
  def create
    result = Sudomock.post("/api/v1/renders", {
      mockup_uuid: ENV.fetch("SUDOMOCK_MOCKUP_UUID"),
      smart_objects: [{
        uuid: ENV.fetch("SUDOMOCK_SMART_OBJECT_UUID"),
        asset: { url: params.require(:artwork_url), fit: "crop" }
      }],
      export_options: {
        image_format: "webp",
        image_size: 2048,
        quality: 90
      }
    })

    files = result.dig("data", "print_files")
    render json: { image_url: files.first["export_path"] }
  rescue Sudomock::Error => error
    render json: { code: error.code, message: error.message },
           status: error.status
  end
end

One render answers with one image, so print_files carries a single entry whatever number of layers the request filled:

{
  "success": true,
  "data": {
    "print_files": [
      {
        "smart_object_uuid": "223e4567-e89b-12d3-a456-426614174001",
        "export_path": "https://cdn.sudomock.com/renders/8f2c1d4e.webp"
      }
    ]
  }
}

fit decides how the artwork meets the slot, and Fit and blend modes shows each result. A long render does not have to hold the connection open: set is_async to true, read job_id from the 202, and follow it from an Active Job worker against the jobs endpoint.

Next steps

Webhooks

Get a signed callback when an asynchronous render finishes, instead of polling for it.

Upload a PSD

Every field the upload accepts, and everything the response names.

Get started

Learn

Resources

Render mockups with Ruby on Rails

Prerequisites

Guide

Next steps

Webhooks

Upload a PSD

​Prerequisites

​Guide

​Next steps

Webhooks

Upload a PSD

Prerequisites

Guide

Next steps