Render mockups from a FastAPI app

This page puts a render behind one of your own routes. A caller posts a mockup id and an artwork URL, your FastAPI service calls SudoMock, and the answer is the URL of a finished image.

Hand this to a coding agent before it wires SudoMock into a FastAPI service.

Open in Cursor

Prerequisites

An API key. Issue one on the API keys page and copy it while it is on screen.
Python 3.9 or newer, which is the floor the client library supports.
One call already made by hand. The quickstart walks the two requests this page wraps in routes.

Guide

Install the client

pip install sudomock

uv add sudomock

poetry add sudomock

The client reads SUDOMOCK_API_KEY from the environment when you pass no key, so local runs and deployed ones can share the same code.

Upload a template once

An upload registers a Photoshop file and reads back the UUID of every slot you can address later. Run it once per template, from a script rather than from a route.

scripts/upload_template.py

import asyncio
import os

from sudomock import AsyncSudoMock

PSD_URL = "https://example.com/tee-front.psd"


async def main() -> None:
    key = os.environ["SUDOMOCK_API_KEY"]
    async with AsyncSudoMock(api_key=key) as client:
        mockup = await client.psd.upload(
            url=PSD_URL,
            name="Tee front",
        )

    print("mockup_uuid:", mockup.uuid)
    for slot in mockup.smart_objects:
        print("smart_object:", slot.uuid, slot.name)


asyncio.run(main())

Store the two ids it prints next to the product they belong to. A render needs nothing else from the file.

Render from a route

One client serves the whole process. Build it in the lifespan, reach it through a dependency, and let pydantic reject a bad body before a credit is spent.

app/main.py

import os
from contextlib import asynccontextmanager
from typing import Literal

from fastapi import Depends, FastAPI, HTTPException, Request
from pydantic import BaseModel, HttpUrl
from sudomock import AsyncSudoMock, RateLimitError, SudoMockError


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.sudomock = AsyncSudoMock(
        api_key=os.environ["SUDOMOCK_API_KEY"],
    )
    yield
    await app.state.sudomock.close()


app = FastAPI(lifespan=lifespan)


def get_client(request: Request) -> AsyncSudoMock:
    return request.app.state.sudomock


class RenderIn(BaseModel):
    mockup_uuid: str
    smart_object_uuid: str
    artwork_url: HttpUrl
    fit: Literal["fit", "fill", "crop"] = "fit"


class RenderOut(BaseModel):
    image_url: str


@app.post("/renders", response_model=RenderOut)
async def create_render(
    body: RenderIn,
    client: AsyncSudoMock = Depends(get_client),
) -> RenderOut:
    try:
        render = await client.renders.create(
            mockup_uuid=body.mockup_uuid,
            smart_objects=[
                {
                    "uuid": body.smart_object_uuid,
                    "asset": {
                        "url": str(body.artwork_url),
                        "fit": body.fit,
                    },
                }
            ],
            export_options={
                "image_format": "webp",
                "image_size": 2048,
            },
        )
    except RateLimitError as exc:
        wait = int(exc.retry_after or 60)
        raise HTTPException(
            status_code=429,
            detail="Render limit reached. Retry shortly.",
            headers={"Retry-After": str(wait)},
        ) from exc
    except SudoMockError as exc:
        raise HTTPException(
            status_code=exc.status_code or 502,
            detail=exc.message,
        ) from exc

    return RenderOut(image_url=render.url)

SudoMockError carries status_code, error_code and message, so one handler can answer a caller properly and still leave the code readable. Errors lists what each code means and which ones are worth retrying.

Use the async client inside async def. The blocking client holds the event loop for the length of a render, which stalls every other request the same worker is serving.

Hand a long render to the queue

A large export can outlive the patience of an HTTP client. Send it with is_async=True, answer 202 with the job id, and let the caller come back for the result.

app/main.py

from typing import Optional


class QueuedOut(BaseModel):
    job_id: str


class JobOut(BaseModel):
    status: str
    image_url: Optional[str] = None


@app.post("/renders/queued", status_code=202)
async def queue_render(
    body: RenderIn,
    client: AsyncSudoMock = Depends(get_client),
) -> QueuedOut:
    job = await client.renders.create(
        mockup_uuid=body.mockup_uuid,
        smart_objects=[
            {
                "uuid": body.smart_object_uuid,
                "asset": {
                    "url": str(body.artwork_url),
                    "fit": body.fit,
                },
            }
        ],
        is_async=True,
    )
    return QueuedOut(job_id=job.job_id)


@app.get("/renders/{job_id}", response_model=JobOut)
async def read_render(
    job_id: str,
    client: AsyncSudoMock = Depends(get_client),
) -> JobOut:
    job = await client.jobs.get(job_id)
    return JobOut(
        status=job.status,
        image_url=job.result_url,
    )

Polling is the simple half. A webhook is the half that scales, because the finished render reaches your service on its own instead of being asked for.

Next steps

Render reference

Every field a render body accepts, with a live request panel.

Webhooks

Get called back when a queued render finishes.

Fit and blend modes

What fit does to artwork that is not the shape of the slot.

Get started

Learn

Resources

Render mockups from a FastAPI app

Prerequisites

Guide

Next steps

Render reference

Webhooks

Fit and blend modes

​Prerequisites

​Guide

​Next steps

Render reference

Webhooks

Fit and blend modes

Prerequisites

Guide

Next steps