Render product mockups with Django

SudoMock renders a mockup from a Photoshop template you upload once. This page wires that into a Django project: the key lives in settings.py, a management command uploads the template, and a view returns the finished image.

Guide an agent through a SudoMock render in Django.

Open in Cursor

Prerequisites

A Django project with an app you can add a view and a command to. The app is called mockups below.
Python 3.9 or later, which the client library requires.
An API key. Keys start with sm_ and travel in the x-api-key header. See API keys.
A public URL to the PSD you want to render, and a public URL to the artwork that goes into it.

If you have not called the API before, Quickstart shows the same two requests as plain HTTP.

Guide

Install the client

pip install sudomock

uv add sudomock

poetry add sudomock

Put the key in settings

Three values belong in the environment: the key, and the two uuids the next step prints. Reading them with os.environ means a missing value stops the project at startup rather than on the first render.

# settings.py
import os

SUDOMOCK_API_KEY = os.environ["SUDOMOCK_API_KEY"]
SUDOMOCK_MOCKUP_UUID = os.environ["SUDOMOCK_MOCKUP_UUID"]
SUDOMOCK_SMART_OBJECT = os.environ["SUDOMOCK_SMART_OBJECT"]

Build the client once and import it where you need it. It reads SUDOMOCK_API_KEY by itself when no key is passed, but taking it from settings keeps every secret on one page.

# mockups/client.py
from django.conf import settings
from sudomock import SudoMock

client = SudoMock(api_key=settings.SUDOMOCK_API_KEY)

Upload the template once

A PSD is uploaded once and rendered many times, so this belongs in a management command rather than in request handling.

# mockups/management/commands/upload_mockup.py
from django.core.management.base import BaseCommand

from mockups.client import client


class Command(BaseCommand):
    help = "Upload a PSD and print the uuids a render needs."

    def add_arguments(self, parser):
        parser.add_argument("psd_url")
        parser.add_argument("name")

    def handle(self, *args, **options):
        mockup = client.psd.upload(
            url=options["psd_url"],
            name=options["name"],
        )
        self.stdout.write(f"mockup: {mockup.uuid}")
        for layer in mockup.smart_objects:
            self.stdout.write(
                f"smart object {layer.name}: {layer.uuid}"
            )

Run it:

python manage.py upload_mockup \
  https://example.com/heavyweight-tee.psd \
  "Heavyweight tee front"

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

Those two uuids are the SUDOMOCK_MOCKUP_UUID and SUDOMOCK_SMART_OBJECT values from the previous step.

Render from a view

The view takes an artwork URL, fills the smart object with it, and answers with the rendered image.

# mockups/views.py
import json

from django.conf import settings
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_POST
from sudomock import SudoMockError

from mockups.client import client


@csrf_exempt
@require_POST
def render_mockup(request):
    artwork_url = json.loads(request.body)["artwork_url"]

    try:
        render = client.renders.create(
            mockup_uuid=settings.SUDOMOCK_MOCKUP_UUID,
            smart_objects=[
                {
                    "uuid": settings.SUDOMOCK_SMART_OBJECT,
                    "asset": {"url": artwork_url, "fit": "crop"},
                }
            ],
            export_options={
                "image_format": "webp",
                "image_size": 1920,
                "quality": 90,
            },
        )
    except SudoMockError as error:
        return JsonResponse(
            {"error": error.message, "code": error.error_code},
            status=error.status_code or 502,
        )

    return JsonResponse({"url": render.url})

csrf_exempt is there because this route is called by your own backend. A route a browser form posts to keeps the token instead.

# mockups/urls.py
from django.urls import path

from mockups import views

urlpatterns = [
    path("renders/", views.render_mockup, name="render"),
]

Call it and read the answer

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

A success answers with the URL of the finished image, taken from render.url. One render answers with one composited image, so render.print_files carries a single entry and render.url is the shortcut to it.A failure answers with the code the API returned:

{
  "error": "Human-readable error message",
  "code": "OUTPUT_RESOLUTION_LIMIT"
}

That code means the requested width is above what the account may render. Every code, and the statuses worth retrying, are in Errors.

A render holds the request open while it runs. Pass is_async=True to get a job id back at once and let a webhook tell you when the image is ready.

Next steps

SDKs

Every resource the Python client exposes, and the Node one.

Errors

Each error_code, and which statuses are worth retrying.

Webhooks

Let a finished render call your Django route back.

Get started

Learn

Resources

Render product mockups with Django

Prerequisites

Guide

Next steps

SDKs

Errors

Webhooks

​Prerequisites

​Guide

​Next steps

SDKs

Errors

Webhooks

Prerequisites

Guide

Next steps