Render mockups with Ruby on Rails

Use this pre-built prompt to get started faster.

Prerequisites

An API key. Create one and keep the sm_ value.
A PSD with at least one visible smart object, at a public URL. Preparing a PSD covers what it needs.

Guide

Add a client

There is no gem to install. Open Rails credentials with bin/rails credentials:edit, put the key there, then let one service object carry the header, the timeout and the failure.

config/credentials.yml.enc

sudomock:
  api_key: sm_your_api_key

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"]
      reason = body["message"] || body["detail"]
      super(reason || "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 answers with a JSON body, and error_code is what you branch on. Errors lists the codes and says which ones are worth retrying.

Upload once, then render from a controller

Upload the PSD once to learn the mockup UUID and the name of every slot inside it. This belongs in a rake task, not in a request, and Upload a PSD covers every field it takes.

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]"

Those UUIDs stay valid for every later render, so they belong in credentials, in the environment, or on the product row they describe. The render call takes them with the artwork and answers with the finished file. Wire the action into config/routes.rb and post the artwork URL to it.

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 }
    })

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

Next steps

Render a PSD mockup

Every field the render call takes, and everything it answers with.

Create a mockup from a PSD

The upload call, field by field.

Retrieve a single job

Follow an asynchronous render through to its finished file.

Fit and blend modes

What fit, fill and crop each do to the artwork.

Photo mockups

Render from a product photo when there is no PSD.

Webhooks

Get a signed callback when an asynchronous render finishes.

Get started

Learn

Resources

Render mockups with Ruby on Rails

Prerequisites

Guide

Next steps

Render a PSD mockup

Create a mockup from a PSD

Retrieve a single job

Fit and blend modes

Photo mockups

Webhooks

​Prerequisites

​Guide

​Next steps

Render a PSD mockup

Create a mockup from a PSD

Retrieve a single job

Fit and blend modes

Photo mockups

Webhooks

Prerequisites

Guide

Next steps