Render product mockups with Python

This page takes a Photoshop file to a finished image from a plain Python script: install the client, upload the template once, then render it as often as you like. If you have not made a request yet, the quickstart runs the same two calls with curl.

Hand this to an AI coding agent that is adding SudoMock renders to a Python project.

Open in Cursor

Prerequisites

Python 3.9 or newer.
An API key from API keys, exported as SUDOMOCK_API_KEY. Keys begin with sm_.
A PSD reachable at a public URL. Preparing a PSD covers what the file needs before you send it.

Guide

Install

pip install sudomock

uv add sudomock

poetry add sudomock

Hold the key in the environment

The client sets the x-api-key header for you. Give it the key from the environment rather than from source, so a repository or a traceback never carries it.

export SUDOMOCK_API_KEY=sm_your_api_key

import os

from sudomock import SudoMock

client = SudoMock(api_key=os.environ["SUDOMOCK_API_KEY"])

SudoMock() with no argument reads SUDOMOCK_API_KEY itself, which is the shorter form when a process already has it.

Upload the template once

An upload parses the PSD and hands back the UUIDs you address in a render: one for the mockup, one for each smart object inside it.

mockup = client.psd.upload(
    url="https://example.com/heavyweight-tee.psd",
    name="Heavyweight tee front",
)

print(mockup.uuid)

for layer in mockup.smart_objects:
    print(layer.uuid, layer.name)

This belongs in your setup, not in your render loop. Store mockup.uuid and the smart object UUID next to the product they describe, and every render after that reuses them.

Render the artwork

renders.create places your image into a smart object and returns the finished file. .url is the first rendered file, which is what a single smart object render produces.

MOCKUP_UUID = "8f2c1d90-6b4e-4a37-9e55-0d1c7a3f21b8"
SMART_OBJECT_UUID = "b41a7e52-93c8-4d61-8f07-2ae5c9d04713"

render = client.renders.create(
    mockup_uuid=MOCKUP_UUID,
    smart_objects=[
        {
            "uuid": SMART_OBJECT_UUID,
            "asset": {
                "url": "https://example.com/artwork.png",
                "fit": "crop",
            },
        }
    ],
    export_options={
        "image_format": "webp",
        "image_size": 2048,
        "quality": 90,
    },
)

print(render.url)

fit decides how the artwork meets the printable area: fit keeps its proportions inside the bounds, crop covers the area and cuts the overflow, fill stretches it to the bounds. Fit and blend modes shows what each one does to the result.

Render in the background instead

A catalogue run does not need to hold a connection open per image. Submit the render, keep the job id, and collect the result when it is done.

job = client.renders.create(
    mockup_uuid=MOCKUP_UUID,
    smart_objects=[
        {
            "uuid": SMART_OBJECT_UUID,
            "asset": {"url": "https://example.com/artwork.png"},
        }
    ],
    is_async=True,
)

finished = client.jobs.wait(job.job_id, timeout=300)

print(finished.status, finished.result_url)

Point a webhook endpoint at your service and the result arrives without polling at all.

Handle the answers you will actually get

Each failure is its own exception, so a script can say something useful instead of printing a traceback. The client already retries a rate limit and a server error a couple of times, which means RateLimitError reaching your code is a signal to slow the whole run down.

from sudomock import (
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    ValidationError,
)

try:
    render = client.renders.create(
        mockup_uuid=MOCKUP_UUID,
        smart_objects=[
            {
                "uuid": SMART_OBJECT_UUID,
                "asset": {
                    "url": "https://example.com/artwork.png",
                },
            }
        ],
    )
except ValidationError as exc:
    raise SystemExit(f"Body rejected: {exc.message}")
except AuthenticationError:
    raise SystemExit("Key missing, revoked or malformed.")
except InsufficientCreditsError as exc:
    raise SystemExit(f"No credits until {exc.credits_reset_at}.")
except RateLimitError as exc:
    raise SystemExit(f"Rate limited. Wait {exc.retry_after}s.")

for warning in render.warnings:
    print(warning.code, warning.message)

print(render.url)

A successful render can still carry advisories on render.warnings, so print them while you are building. Error codes lists every error_code and which failures are safe to retry.

Get started

Learn

Resources

Render product mockups with Python

Prerequisites

Guide

Next steps

Render a product photo

Webhooks

​Prerequisites

​Guide

​Next steps

Render a product photo

Webhooks

Prerequisites

Guide

Next steps