Render product mockups with Next.js

A route handler takes an artwork URL, drops it into a Photoshop template you uploaded once, and answers with the finished image. The key stays on the server, so nothing in the browser bundle can read it.

Use this prompt to get an agent writing the call correctly.

Open in Cursor

Prerequisites

An API key from your dashboard. Keys start with sm_.
Node.js 20 or newer. The setup script below reads .env.local with --env-file, which arrived in 20.6.
A Next.js app, App Router or Pages Router.

Guide

Install

Add the Node SDK to your project.

npm install sudomock

pnpm add sudomock

yarn add sudomock

bun add sudomock

Add your key

Put the key in .env.local. Next.js loads that file for you in next dev and next build, so a route handler reads it with no further setup.

.env.local

SUDOMOCK_API_KEY=sm_your_api_key

Leave the NEXT_PUBLIC_ prefix off. It inlines the value into the browser bundle, and a key in a bundle is a key anyone can copy.

Upload the template once

A PSD becomes a reusable template on your account, so this belongs in your setup rather than in the request path. Run it once and keep the two UUIDs it prints.

scripts/upload-mockup.mjs

import SudoMock from 'sudomock'

const sudomock = new SudoMock(process.env.SUDOMOCK_API_KEY)

const mockup = await sudomock.uploads.create({
  psdFileUrl: 'https://example.com/heavyweight-tee.psd',
  psdName: 'Heavyweight tee front',
})

console.log('mockup', mockup.uuid)
for (const layer of mockup.smartObjects) {
  console.log('smart object', layer.name, layer.uuid)
}

node --env-file=.env.local scripts/upload-mockup.mjs

The response also carries textLayers, which is how you swap copy on the same template later.

Render from a route handler

The handler takes an artwork URL, fills the smart object with it, and returns the image URL. Pick the tab for your router.

import SudoMock, { SudoMockError } from 'sudomock'

const sudomock = new SudoMock(process.env.SUDOMOCK_API_KEY)

// Both UUIDs come from step 3.
const MOCKUP = '8f2c1d90-6b4e-4a37-9e55-0d1c7a3f21b8'
const SMART_OBJECT = 'b41a7e52-93c8-4d61-8f07-2ae5c9d04713'

export async function POST(request: Request) {
  const { artworkUrl } = await request.json()

  try {
    const render = await sudomock.renders.create({
      mockupId: MOCKUP,
      smartObjects: [
        {
          uuid: SMART_OBJECT,
          asset: { url: artworkUrl, fit: 'cover' },
        },
      ],
      exportOptions: {
        imageFormat: 'webp',
        imageSize: 1600,
      },
    })

    return Response.json({ url: render.url })
  } catch (error) {
    if (error instanceof SudoMockError) {
      return Response.json(
        { error: error.message, code: error.code },
        { status: error.status || 502 },
      )
    }
    throw error
  }
}

import type { NextApiRequest, NextApiResponse } from 'next'
import SudoMock, { SudoMockError } from 'sudomock'

const sudomock = new SudoMock(process.env.SUDOMOCK_API_KEY)

// Both UUIDs come from step 3.
const MOCKUP = '8f2c1d90-6b4e-4a37-9e55-0d1c7a3f21b8'
const SMART_OBJECT = 'b41a7e52-93c8-4d61-8f07-2ae5c9d04713'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
    const render = await sudomock.renders.create({
      mockupId: MOCKUP,
      smartObjects: [
        {
          uuid: SMART_OBJECT,
          asset: { url: req.body.artworkUrl, fit: 'cover' },
        },
      ],
      exportOptions: {
        imageFormat: 'webp',
        imageSize: 1600,
      },
    })

    res.status(200).json({ url: render.url })
  } catch (error) {
    if (error instanceof SudoMockError) {
      res.status(error.status || 502).json({
        error: error.message,
        code: error.code,
      })
      return
    }
    throw error
  }
}

Every SudoMock failure arrives as a SudoMockError carrying status and code, so one branch covers a rejected key, a missing template and a rate limit alike. A connection failure or a client side timeout reports status as 0, which is why the fallback above exists.

Call it

Start the dev server and post an artwork URL to the route.

curl -X POST http://localhost:3000/api/render \
  -H "Content-Type: application/json" \
  -d '{"artworkUrl":"https://example.com/artwork.png"}'

The reply carries one field, url, pointing at the rendered image. Feed it to next/image, attach it to the order, or store it. When a render fills several smart objects, render.printFiles holds one entry per filled layer, each with its own exportPath.

A render that outlives your function time limit is better submitted in the background. Pass isAsync: true to renders.create, answer the request straight away, and let a webhook tell you when the image is ready.

Next steps

Fit and blend modes

What fit and blending_mode do to the artwork you place.

Webhooks

Get called back when a background render finishes.

Errors

Every status and error_code, and which ones are worth a retry.

Node SDK

The rest of the client: templates, photo mockups, jobs, fonts.

Get started

Learn

Resources

Render product mockups with Next.js

Prerequisites

Guide

Next steps

Fit and blend modes

Webhooks

Errors

Node SDK

​Prerequisites

​Guide

​Next steps

Fit and blend modes

Webhooks

Errors

Node SDK

Prerequisites

Guide

Next steps