Render mockups from a Go service

A Go service reaches SudoMock in two JSON calls, and the standard library covers both. net/http makes the request, encoding/json shapes the body, and go.mod stays empty. This page builds a small package around those two calls, then a route that answers with a finished image. The official client libraries are Node and Python. In Go you call the API directly, which is what the code below does.

Rules for an agent adding SudoMock to a Go service.

Open in Cursor

Prerequisites

Go 1.22 or newer. The route below uses method patterns in http.ServeMux.
An API key from API keys. Keys begin with sm_.
A PSD holding at least one smart object. See Preparing a PSD.
The same two calls in cURL, if you want them side by side: Quickstart.

Guide

Set up the module

go mod init example.com/storefront
export SUDOMOCK_API_KEY="sm_your_api_key"

go mod init example.com/storefront
$env:SUDOMOCK_API_KEY = "sm_your_api_key"

No go get follows. The key lives in the environment, so it never reaches the binary and never reaches a commit.

Write the client

One *http.Client serves the whole process and carries the timeout. post is the only place the x-api-key header is set, so no later call can forget it, and any reply that is not 200 becomes an APIError holding the status, the error_code and the message the API returned.

mockups/client.go

package mockups

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const baseURL = "https://api.sudomock.com"

// Client calls the SudoMock API with one account key.
type Client struct {
	apiKey string
	http   *http.Client
}

// New reads the key from the environment, so it stays out
// of the binary and out of source control.
func New() (*Client, error) {
	key := os.Getenv("SUDOMOCK_API_KEY")
	if key == "" {
		return nil, fmt.Errorf("SUDOMOCK_API_KEY is empty")
	}
	return &Client{
		apiKey: key,
		http:   &http.Client{Timeout: 120 * time.Second},
	}, nil
}

// APIError is a failed call, kept whole so a caller can
// branch on ErrorCode instead of parsing a string.
type APIError struct {
	Status    int    `json:"-"`
	ErrorCode string `json:"error_code"`
	Detail    string `json:"detail"`
	Message   string `json:"message"`
	Body      string `json:"-"`
}

func (e *APIError) Error() string {
	text := e.Detail
	if text == "" {
		text = e.Message
	}
	if text == "" {
		text = e.Body
	}
	if e.ErrorCode != "" {
		return fmt.Sprintf("sudomock %d %s: %s",
			e.Status, e.ErrorCode, text)
	}
	return fmt.Sprintf("sudomock %d: %s", e.Status, text)
}

func (c *Client) post(
	ctx context.Context, path string, in, out any,
) error {
	body, err := json.Marshal(in)
	if err != nil {
		return err
	}

	req, err := http.NewRequestWithContext(
		ctx, http.MethodPost, baseURL+path,
		bytes.NewReader(body),
	)
	if err != nil {
		return err
	}
	req.Header.Set("x-api-key", c.apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := c.http.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()

	payload, err := io.ReadAll(res.Body)
	if err != nil {
		return err
	}
	if res.StatusCode != http.StatusOK {
		apiErr := &APIError{
			Status: res.StatusCode,
			Body:   string(payload),
		}
		_ = json.Unmarshal(payload, apiErr)
		return apiErr
	}
	return json.Unmarshal(payload, out)
}

Upload the PSD once

POST /api/v1/psd/upload takes a public URL to the file and answers with the mockup plus every layer inside it. Those layer UUIDs are what a render addresses, so this call is also how you learn what you can change.

mockups/upload.go

package mockups

import "context"

// UploadRequest is the body of POST /api/v1/psd/upload.
type UploadRequest struct {
	PSDFileURL string `json:"psd_file_url"`
	PSDName    string `json:"psd_name,omitempty"`
}

// SmartObject is one layer a render can address.
type SmartObject struct {
	UUID      string `json:"uuid"`
	LayerName string `json:"layer_name"`
}

type uploadResponse struct {
	Data struct {
		UUID         string        `json:"uuid"`
		SmartObjects []SmartObject `json:"smart_objects"`
	} `json:"data"`
}

// Upload registers a PSD and returns its mockup UUID with
// every smart object found inside it.
func (c *Client) Upload(
	ctx context.Context, in UploadRequest,
) (string, []SmartObject, error) {
	var res uploadResponse
	err := c.post(ctx, "/api/v1/psd/upload", in, &res)
	if err != nil {
		return "", nil, err
	}
	return res.Data.UUID, res.Data.SmartObjects, nil
}

Run it from a one-off command rather than from the service.

cmd/upload/main.go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"example.com/storefront/mockups"
)

func main() {
	if len(os.Args) < 2 {
		log.Fatal("usage: upload <psd-url>")
	}

	client, err := mockups.New()
	if err != nil {
		log.Fatal(err)
	}

	uuid, layers, err := client.Upload(
		context.Background(),
		mockups.UploadRequest{
			PSDFileURL: os.Args[1],
			PSDName:    "Heavyweight tee front",
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("mockup_uuid:", uuid)
	for _, l := range layers {
		fmt.Printf("  %s  %s\n", l.UUID, l.LayerName)
	}
}

go run ./cmd/upload https://example.com/heavyweight-tee.psd

mockup_uuid: 8f2c1d90-6b4e-4a37-9e55-0d1c7a3f21b8
  b41a7e52-93c8-4d61-8f07-2ae5c9d04713  Front print

Keep both UUIDs in configuration. The template is registered now, and every render from here reuses it.

Render from a route

POST /api/v1/renders takes the mockup UUID, the smart object to fill and the artwork that goes into it. fit decides how the artwork meets the layer area: crop covers the area and cuts the overflow while keeping proportions.

mockups/render.go

package mockups

import (
	"context"
	"fmt"
)

// Asset is the artwork that goes into a smart object.
// Fit is one of fill, fit or crop.
type Asset struct {
	URL string `json:"url,omitempty"`
	Fit string `json:"fit,omitempty"`
}

// SmartObjectInput fills one smart object by UUID.
type SmartObjectInput struct {
	UUID  string `json:"uuid"`
	Asset *Asset `json:"asset,omitempty"`
}

// ExportOptions shapes the output file. ImageFormat is one
// of png, jpg or webp.
type ExportOptions struct {
	ImageFormat string `json:"image_format"`
	ImageSize   int    `json:"image_size"`
	Quality     int    `json:"quality"`
}

// RenderRequest is the body of POST /api/v1/renders.
type RenderRequest struct {
	MockupUUID    string             `json:"mockup_uuid"`
	SmartObjects  []SmartObjectInput `json:"smart_objects"`
	ExportOptions ExportOptions      `json:"export_options"`
}

type renderResponse struct {
	Data struct {
		PrintFiles []struct {
			ExportPath string `json:"export_path"`
		} `json:"print_files"`
		RenderUUID string `json:"render_uuid"`
	} `json:"data"`
}

// Render returns the URL of the finished image.
func (c *Client) Render(
	ctx context.Context, in RenderRequest,
) (string, error) {
	var res renderResponse
	err := c.post(ctx, "/api/v1/renders", in, &res)
	if err != nil {
		return "", err
	}
	if len(res.Data.PrintFiles) == 0 {
		return "", fmt.Errorf("render returned no file")
	}
	return res.Data.PrintFiles[0].ExportPath, nil
}

The handler takes an artwork URL from the caller and hands back the rendered image. Everything else about the mockup is fixed configuration.

main.go

package main

import (
	"encoding/json"
	"errors"
	"log"
	"net/http"
	"os"

	"example.com/storefront/mockups"
)

var (
	client     *mockups.Client
	mockupUUID = os.Getenv("SUDOMOCK_MOCKUP_UUID")
	layerUUID  = os.Getenv("SUDOMOCK_LAYER_UUID")
)

type request struct {
	ArtworkURL string `json:"artwork_url"`
}

func handleRender(w http.ResponseWriter, r *http.Request) {
	var body request
	err := json.NewDecoder(r.Body).Decode(&body)
	if err != nil || body.ArtworkURL == "" {
		http.Error(w, "artwork_url is required",
			http.StatusBadRequest)
		return
	}

	req := mockups.RenderRequest{
		MockupUUID: mockupUUID,
		SmartObjects: []mockups.SmartObjectInput{{
			UUID: layerUUID,
			Asset: &mockups.Asset{
				URL: body.ArtworkURL,
				Fit: "crop",
			},
		}},
		ExportOptions: mockups.ExportOptions{
			ImageFormat: "webp",
			ImageSize:   1920,
			Quality:     90,
		},
	}

	image, err := client.Render(r.Context(), req)
	if err != nil {
		var apiErr *mockups.APIError
		if errors.As(err, &apiErr) {
			log.Printf("render %d %s",
				apiErr.Status, apiErr.ErrorCode)
		}
		http.Error(w, "render failed", http.StatusBadGateway)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]string{
		"image": image,
	})
}

func main() {
	var err error
	if client, err = mockups.New(); err != nil {
		log.Fatal(err)
	}

	mux := http.NewServeMux()
	mux.HandleFunc("POST /renders", handleRender)
	log.Fatal(http.ListenAndServe(":8080", mux))
}

Point the service at the two UUIDs from the previous step and start it.

export SUDOMOCK_MOCKUP_UUID="8f2c1d90-6b4e-4a37-9e55-0d1c7a3f21b8"
export SUDOMOCK_LAYER_UUID="b41a7e52-93c8-4d61-8f07-2ae5c9d04713"
go run .

curl -X POST http://localhost:8080/renders \
  -H "Content-Type: application/json" \
  -d '{"artwork_url": "https://example.com/artwork.png"}'

The reply carries data.print_files[0].export_path, the URL of the finished image. Serve it to the page or store it against the order. A key bound to a custom domain serves that URL from your own domain, with nothing to pass per request.This render holds the connection until the image exists. For a long job set is_async to true, take the job_id from the 202, and either poll GET /api/v1/jobs/{job_id} or let a webhook call you.

Read a failure

APIError already carries the status and the error_code, so a caller branches on values rather than matching strings.

var apiErr *mockups.APIError
if errors.As(err, &apiErr) {
	switch apiErr.Status {
	case http.StatusTooManyRequests:
		// A limit was hit. Wait out Retry-After,
		// then try again.
	case http.StatusBadGateway:
		// Upstream trouble. Retry with backoff.
	case http.StatusPaymentRequired:
		// Not a retry. Read apiErr.ErrorCode, then
		// fix the request or the billing state.
	}
}

An account on trial credits renders at most 1024 px wide, and a larger image_size comes back as 402 with error_code OUTPUT_RESOLUTION_LIMIT rather than a quietly smaller image.

Next steps

Fit and blend modes

What fit and blending_mode do to the result.

Webhooks

Let a long render call your service back.

Errors

Every error code, and which statuses are worth retrying.

Get started

Learn

Resources

Render mockups from a Go service

Prerequisites

Guide

Next steps

Fit and blend modes

Webhooks

Errors

​Prerequisites

​Guide

​Next steps

Fit and blend modes

Webhooks

Errors

Prerequisites

Guide

Next steps