What is a mockup data model?

A mockup data model defines the structure of your mockup configuration - including Smart Object positions, layer names, transformation settings, and output parameters. It's essentially a blueprint that tells the API how to process your PSD template.

How do I identify Smart Object layers in my PSD?

Smart Object layers can be identified by their layer type in Photoshop (shown with a special icon) or programmatically through the API. SudoMock provides an inspection endpoint that returns all Smart Object layers with their names, positions, and dimensions.

Can I update multiple Smart Objects in one API call?

Yes, you can target multiple Smart Objects in a single API request by providing an array of layer configurations. Each configuration specifies the Smart Object name and the image URL to insert, allowing batch updates efficiently.

What happens if a Smart Object name doesn't match?

If the specified Smart Object name doesn't exist in the PSD, the API will return an error indicating the layer wasn't found. Always verify layer names using the inspection endpoint before making render requests.

How do transformations affect the inserted design?

Transformations (scale, rotation, perspective) applied to the Smart Object in Photoshop are automatically applied to any content inserted via the API. This ensures your designs appear with the same realistic warping and positioning as seen in the original template.

Mockup API Data Model Guide: PSD Rendering

Understanding how mockup APIs structure their data is crucial for building robust integrations. This guide covers the de-facto standard data model used across the industry, what each field means, and how to use them effectively in your code.

size vs position - Visual Explanation

size

3951 x 4800

Your design canvas

4800px

3951px

Design Resolution

Upload assets at this size

→

scales to

position

507 x 620

x: 771, y: 886

Mockup Canvas

Rendered Position

Where it appears on mockup

size = Original design dimensions

position = Rendered bounds on canvas

The De-Facto Standard: Rect + Transform

Every major design tool and mockup API uses the same fundamental data model: a rectangle with position coordinates and optional transforms. This pattern comes from decades of graphics programming, from Photoshop to Canvas2D to WebGL.

x, y

Position

Top-left corner coordinates

w, h

Size

Width and height dimensions

deg

Rotation

Optional rotation angle

quad

Transform

4-point perspective

This model is universal because it's deterministic, minimal, and fast. Whether you're working with Photoshop layers, Figma frames, or mockup APIs, the core concept remains the same: define a bounding box and optionally transform it.

Anatomy of a Smart Object Response

When you upload a PSD to SudoMock, each smart object layer returns detailed metadata. Let's break down what each field means and how to use it:

Smart Object Response Structure

json

1{
2"uuid": "73957ff7-82c4-4c14-947a-a6f841944d1c",
3"name": "print_area",
4"size": {
5  "width": 3951,
6  "height": 4800
7},
8"position": {
9  "x": 771,
10  "y": 886,
11  "width": 507,
12  "height": 620
13},
14"quad": [
15  [771, 886],
16  [1278, 886],
17  [1278, 1506],
18  [771, 1506]
19],
20"blend_mode": "BlendMode.NORMAL",
21"layer_name": "print_area"
22}

Understanding Each Field

size (width, height) - The original dimensions of the embedded smart object content. This is your design canvas size - upload assets at this resolution for best quality. The render API works in these coordinates.

position.x, position.y - Top-left corner placement coordinates on the mockup canvas. Useful for client-side canvas preview overlays.

position.width, position.height - Display dimensions after transforms. Primary use: drawing design previews on thumbnail images in browser. Not used in render API requests.

quad (4 points) - Pre-calculated corner coordinates for perspective rendering. Useful for canvas-based rendering or custom transform implementations.

blend_mode - How this layer blends with layers below. Important for color overlays (multiply) or special effects (screen, overlay).

size vs position: The Key Distinction

The most important concept to understand is the difference between size and position. They represent two different things:

Field	Represents	Use Case
size.width	Embedded content width (3951px)	Render API coordinates, design canvas
size.height	Embedded content height (4800px)	Render API coordinates, design canvas
position.x	Left edge on mockup (771px)	Client-side canvas preview
position.y	Top edge on mockup (886px)	Client-side canvas preview
position.width	Display width (507px)	Thumbnail overlay drawing
position.height	Display height (620px)	Thumbnail overlay drawing

Think of it this way

size = "Upload your design at this resolution, send coordinates in render API"
position = "Use this for drawing previews on thumbnail images in browser"

In the example above, a 3951x4800 design gets scaled down to 507x620 when rendered on the mockup canvas. The scale factor is approximately 0.128x (507/3951).

Working with Quad Coordinates

The quad array contains four [x, y] coordinate pairs representing the corners of the smart object's bounding box. This is especially useful for:

Canvas rendering - Draw directly using canvas 2D context with precise coordinates

Perspective transforms - Handle non-rectangular smart objects (skewed, rotated)

Hit testing - Determine if a point is inside the smart object area

Custom overlays - Position UI elements or annotations accurately

Using quad coordinates in JavaScript

javascript

1// Draw smart object bounds on canvas
2function drawSmartObjectBounds(ctx, smartObject) {
3const [topLeft, topRight, bottomRight, bottomLeft] = smartObject.quad;
4
5ctx.beginPath();
6ctx.moveTo(topLeft[0], topLeft[1]);
7ctx.lineTo(topRight[0], topRight[1]);
8ctx.lineTo(bottomRight[0], bottomRight[1]);
9ctx.lineTo(bottomLeft[0], bottomLeft[1]);
10ctx.closePath();
11ctx.strokeStyle = '#00ff00';
12ctx.stroke();
13}
14
15// Check if a point is inside the smart object
16function isPointInQuad(point, quad) {
17const [tl, tr, br, bl] = quad;
18// Simple bounding box check (for rectangular quads)
19return point.x >= tl[0] && point.x <= tr[0] &&
20       point.y >= tl[1] && point.y <= bl[1];
21}

Integration Patterns

Integration Flow

📤

Upload PSD

/psd/upload

→

📋

Get Metadata

size, position, quad

→

🎨

Render

/renders

→

🖼️

Result

WebP/PNG URL

Pattern 1: Basic Render Request

The most common pattern is uploading a PSD, storing the smart object metadata, then using it to render variations:

Complete integration flow

javascript

1// Step 1: Upload PSD and store metadata
2const uploadResponse = await fetch('https://api.sudomock.com/api/v1/psd/upload', {
3method: 'POST',
4headers: {
5  'X-API-KEY': API_KEY,
6  'Content-Type': 'application/json'
7},
8body: JSON.stringify({
9  psd_file_url: 'https://storage.example.com/tshirt-mockup.psd',
10  psd_name: 'T-Shirt Front'
11})
12});
13
14const { data: mockup } = await uploadResponse.json();
15
16// Store the mockup metadata for later use
17const mockupId = mockup.uuid;
18const smartObjects = mockup.smart_objects;
19
20// Find the main design area
21const designArea = smartObjects.find(so => so.name === 'print_area');
22console.log('Design canvas size:', designArea.size); // { width: 3951, height: 4800 }
23console.log('Rendered position:', designArea.position); // { x: 771, y: 886, width: 507, height: 620 }
24
25// Step 2: Render with a design
26const renderResponse = await fetch('https://api.sudomock.com/api/v1/renders', {
27method: 'POST',
28headers: {
29  'X-API-KEY': API_KEY,
30  'Content-Type': 'application/json'
31},
32body: JSON.stringify({
33  mockup_uuid: mockupId,
34  smart_objects: [{
35    uuid: designArea.uuid,
36    asset: {
37      url: 'https://storage.example.com/my-design.png',
38      fit: 'cover' // cover, contain, or fill
39    }
40  }],
41  export_options: {
42    image_format: 'webp',
43    image_size: 1920,
44    quality: 95
45  }
46})
47});
48
49const { data: render } = await renderResponse.json();
50console.log('Rendered mockup:', render.print_files[0].export_path);

Pattern 2: Using Position Data for Custom Rendering

If you're building a custom preview or need to render locally, the position data tells you exactly where to place the design:

Custom canvas preview

javascript

1async function createPreview(mockupImage, designImage, smartObject) {
2const canvas = document.createElement('canvas');
3const ctx = canvas.getContext('2d');
4
5// Set canvas to mockup dimensions
6canvas.width = mockupImage.width;
7canvas.height = mockupImage.height;
8
9// Draw the mockup background
10ctx.drawImage(mockupImage, 0, 0);
11
12// Get position data from API response
13const { x, y, width, height } = smartObject.position;
14
15// Draw the design at the correct position and size
16ctx.drawImage(designImage, x, y, width, height);
17
18return canvas.toDataURL('image/png');
19}
20
21// Usage
22const preview = await createPreview(
23await loadImage(mockupThumbnail),
24await loadImage(myDesign),
25designArea
26);

Design Resolution

For best quality, prepare your design at the size dimensions (e.g., 3951x4800), not the position dimensions. The API handles scaling automatically.

Working with Blend Modes

The blend_mode field indicates how the smart object layer blends with layers below it in the PSD. Common modes include:

Blend Mode	Effect	Common Use
NORMAL	Standard opacity blending	Regular design placement
MULTIPLY	Darkens, whites become transparent	Color overlays, fabric textures
SCREEN	Lightens, blacks become transparent	Light effects, glows
OVERLAY	Combines multiply and screen	Contrast enhancement

For color smart objects (used to change product colors), MULTIPLY is typically used so the design texture shows through the color overlay — common in drinkware mockups and apparel templates.

Next.js Integration Examples

Here are practical examples for integrating SudoMock into your Next.js application. You can use any template from SudoMock's mockup library as a starting point. These examples show how to use the smart object metadata in real frontend code.

SudoMock Client Utility

First, create a reusable client for making API calls to SudoMock:

lib/sudomock.ts

typescript

1// SudoMock API Client for Next.js
2// Store your API key in .env.local as SUDOMOCK_API_KEY
3
4const API_KEY = process.env.SUDOMOCK_API_KEY!
5const BASE_URL = 'https://api.sudomock.com/api/v1'
6
7export interface SmartObject {
8uuid: string
9name: string
10size: { width: number; height: number }
11position: { x: number; y: number; width: number; height: number }
12quad: [number, number][]
13blend_mode: string
14}
15
16export interface MockupData {
17uuid: string
18name: string
19thumbnail: string
20width?: number   // Original PSD width
21height?: number  // Original PSD height
22smart_objects: SmartObject[]
23}
24
25// Upload a PSD and get smart object metadata
26export async function uploadPsd(psdUrl: string, name: string): Promise<MockupData> {
27const response = await fetch(`${BASE_URL}/psd/upload`, {
28  method: 'POST',
29  headers: {
30    'X-API-KEY': API_KEY,
31    'Content-Type': 'application/json',
32  },
33  body: JSON.stringify({
34    psd_file_url: psdUrl,
35    psd_name: name,
36  }),
37})
38
39const data = await response.json()
40if (!data.success) throw new Error(data.detail)
41return data.data
42}
43
44// Render a mockup with a design
45export async function renderMockup(
46mockupId: string,
47smartObjectId: string,
48designUrl: string
49): Promise<string> {
50const response = await fetch(`${BASE_URL}/renders`, {
51  method: 'POST',
52  headers: {
53    'X-API-KEY': API_KEY,
54    'Content-Type': 'application/json',
55  },
56  body: JSON.stringify({
57    mockup_uuid: mockupId,
58    smart_objects: [{
59      uuid: smartObjectId,
60      asset: { url: designUrl, fit: 'cover' }
61    }],
62    export_options: {
63      image_format: 'webp',
64      image_size: 1920,
65      quality: 95
66    }
67  }),
68})
69
70const data = await response.json()
71if (!data.success) throw new Error(data.detail)
72return data.data.print_files[0].export_path
73}

React Hook for Managing Mockups

A custom hook that manages mockup state and provides useful computed values from the smart object metadata:

hooks/useMockupEditor.ts

typescript

1export function useMockupEditor(initialMockup?: MockupData) {
2const [mockup, setMockup] = useState<MockupData | null>(initialMockup ?? null)
3const [selectedDesign, setSelectedDesign] = useState<string | null>(null)
4
5// Find the main print area smart object
6const printArea = useMemo(() => {
7  return mockup?.smart_objects.find(
8    so => so.name.toLowerCase().includes('print') ||
9          so.name.toLowerCase().includes('design')
10  )
11}, [mockup])
12
13// Calculate design requirements from size field
14const designRequirements = useMemo(() => {
15  if (!printArea) return null
16
17  const { width, height } = printArea.size
18  return {
19    width,
20    height,
21    aspectRatio: width / height,
22    megapixels: (width * height) / 1000000,
23    recommendation: width >= 3000
24      ? 'High resolution - perfect for print'
25      : 'Medium resolution - good for web'
26  }
27}, [printArea])
28
29// Get render position info from position field
30const renderPosition = useMemo(() => {
31  if (!printArea) return null
32
33  const { x, y, width, height } = printArea.position
34  const originalSize = printArea.size
35
36  return {
37    x,
38    y,
39    width,
40    height,
41    scaleFactor: width / originalSize.width,
42    // Useful for canvas preview
43    bounds: { left: x, top: y, right: x + width, bottom: y + height }
44  }
45}, [printArea])
46
47return {
48  mockup,
49  setMockup,
50  printArea,
51  designRequirements,
52  renderPosition,
53  selectedDesign,
54  setSelectedDesign,
55}
56}

Live Preview with Canvas

Use the position data to create a real-time preview before rendering:

components/MockupPreview.tsx

typescript

1interface PreviewProps {
2mockupThumbnailUrl: string
3designImageUrl: string | null
4// From smart_object.position in API response
5position: { x: number; y: number; width: number; height: number }
6}
7
8export function MockupPreview({ mockupThumbnailUrl, designImageUrl, position }: PreviewProps) {
9const canvasRef = useRef<HTMLCanvasElement>(null)
10const [previewDataUrl, setPreviewDataUrl] = useState<string | null>(null)
11
12useEffect(() => {
13  if (!designImageUrl || !canvasRef.current) return
14
15  const canvas = canvasRef.current
16  const ctx = canvas.getContext('2d')
17  if (!ctx) return
18
19  // Load both images
20  const mockupImg = new Image()
21  const designImg = new Image()
22  mockupImg.crossOrigin = 'anonymous'
23  designImg.crossOrigin = 'anonymous'
24
25  Promise.all([
26    new Promise<void>(resolve => { mockupImg.onload = () => resolve(); mockupImg.src = mockupThumbnailUrl }),
27    new Promise<void>(resolve => { designImg.onload = () => resolve(); designImg.src = designImageUrl }),
28  ]).then(() => {
29    // Set canvas to mockup size
30    canvas.width = mockupImg.width
31    canvas.height = mockupImg.height
32
33    // Draw mockup background
34    ctx.drawImage(mockupImg, 0, 0)
35
36    // Draw design at the exact position from API
37    // The position object tells us exactly where to place it!
38    ctx.drawImage(
39      designImg,
40      position.x,      // x coordinate from API
41      position.y,      // y coordinate from API
42      position.width,  // rendered width from API
43      position.height  // rendered height from API
44    )
45
46    setPreviewDataUrl(canvas.toDataURL('image/png'))
47  })
48}, [mockupThumbnailUrl, designImageUrl, position])
49
50return (
51  <div className="relative aspect-square bg-slate-800 rounded-lg overflow-hidden">
52    <canvas ref={canvasRef} className="hidden" />
53    {previewDataUrl && (
54      <img src={previewDataUrl} alt="Preview" className="w-full h-full object-contain" />
55    )}
56  </div>
57)
58}

Server Action for Batch Rendering

Process multiple designs in parallel using Next.js Server Actions:

actions/batch-render.ts

typescript

1'use server'
2
3interface BatchResult {
4designUrl: string
5renderUrl: string | null
6success: boolean
7error?: string
8}
9
10export async function batchRenderMockups(
11mockupId: string,
12smartObjectId: string,
13designUrls: string[]
14): Promise<BatchResult[]> {
15// Process 5 at a time to respect rate limits
16const CONCURRENCY = 5
17const results: BatchResult[] = []
18
19for (let i = 0; i < designUrls.length; i += CONCURRENCY) {
20  const batch = designUrls.slice(i, i + CONCURRENCY)
21
22  const batchResults = await Promise.all(
23    batch.map(async (designUrl): Promise<BatchResult> => {
24      try {
25        const renderUrl = await renderMockup(mockupId, smartObjectId, designUrl)
26        return { designUrl, renderUrl, success: true }
27      } catch (error) {
28        return {
29          designUrl,
30          renderUrl: null,
31          success: false,
32          error: error instanceof Error ? error.message : 'Unknown error'
33        }
34      }
35    })
36  )
37
38  results.push(...batchResults)
39}
40
41return results
42}

Environment Variables

Store your SudoMock API key in .env.local as SUDOMOCK_API_KEY. Never expose it in client-side code - always call SudoMock from Server Components, Server Actions, or API routes.

Key Takeaways

size is your design canvas AND API coordinates - Prepare designs at size dimensions. Send size/position values in render API requests. Backend handles embedded→display scaling automatically.

position is for client-side preview only - Use position.x/y/width/height when drawing design overlays on thumbnail images in browser. Not needed for API render requests.

quad enables advanced transforms - For perspective mockups or canvas-based rendering, quad coordinates give you precise control.

blend_mode matters for colors - Understanding blend modes helps you work with color-changing smart objects correctly.

Related Resources

Upload PSD API Reference

Complete documentation for the upload endpoint

Render API Reference

All render options and parameters

Smart Objects Guide

Best practices for preparing PSD templates

API Best Practices

Error handling and parallel processing

Understanding Mockup API Data Models: A Technical Guide

TL;DR

Key Takeaways:

The De-Facto Standard: Rect + Transform

Anatomy of a Smart Object Response

Understanding Each Field

size vs position: The Key Distinction

Working with Quad Coordinates

Integration Patterns

Pattern 1: Basic Render Request

Pattern 2: Using Position Data for Custom Rendering

Working with Blend Modes

Next.js Integration Examples

SudoMock Client Utility

React Hook for Managing Mockups

Live Preview with Canvas

Server Action for Batch Rendering

Key Takeaways

Related Resources

Upload PSD API Reference

Render API Reference

Smart Objects Guide

API Best Practices

Frequently Asked Questions

Related Articles

API Integration Best Practices

Ready to Try SudoMock?