POST

Render Mockup

Generate production-ready mockups by compositing your designs into uploaded PSD templates. CDN-hosted output, multiple export formats.

POST/api/v1/renders

<1s avg

Production Ready

Built for high-volume automation with 2B+ renders processed. CDN-hosted output URLs.

base64 is Recommended (50-500ms faster)

Sending your image as base64 eliminates server-side download latency entirely. The server decodes the image instantly instead of fetching it over HTTP. For high-volume automation, this can save 50-500ms per render compared to URL-based delivery. Image source priority: base64 > url.

Request

Headers

x-api-keystring

Your SudoMock API key starting with sm_. Required unless using Bearer token authentication.

Authorizationstring

Alternative to x-api-key. Use Bearer <JWT> with a Supabase JWT token for dashboard/frontend requests. Format: Bearer eyJhbGciOi...

Content-TypestringRequired

Must be application/json

Authentication

Provide either x-api-key or Authorization: Bearer <JWT>. API keys are recommended for server-to-server integrations. Bearer tokens are used by the dashboard and frontend applications.

Request Body

mockup_uuidstringRequired

UUID of the mockup to render. Must be a valid UUID format (e.g., c315f78f-d2c7-4541-b240-a9372842de94). Obtained from the POST /psd/upload or GET /mockups response.

smart_objectsarrayRequired

Array of smart object configurations to render. Must contain at least 1 item. Each smart object must have either an asset, a color, or both.

export_optionsobject

Output format, size, and quality settings. All fields have defaults, so this entire object is optional.

export_labelstring

Optional label for the export file naming. Max 100 characters. Used as a prefix in the output filename.

Smart Object Configuration

Asset or Color Required

Each smart object must have at least an asset (image), a color overlay, or both. Omitting both will return a 422 validation error.

uuidstringRequired

UUID of the smart object to fill (from upload response). Must be a valid UUID format.

assetobject

Image asset configuration. Either asset or color (or both) must be provided.

asset.base64string

Raw base64-encoded image bytes (no data: prefix). RECOMMENDED: eliminates server-side download latency (50-500ms faster than URL). Either base64 or url must be provided.

asset.urlstring

URL to the image (HTTP/HTTPS or data: URL). Server downloads the image, adding network latency. Either url or base64 must be provided.

asset.content_typestring

MIME type when using the base64 field. Must match pattern: image/png, image/jpeg, image/webp, or image/gif. Defaults to image/png if omitted.

asset.fitenum= fill

How to fit the image in the smart object area. fill = stretch to fill entire bounds (may distort). contain = fit inside preserving aspect ratio (may leave empty space). cover = fill and crop excess (no distortion, no empty space).

asset.rotateinteger= 0

Rotation angle in degrees (-360 to 360)

asset.flip_horizontalboolean= false

Flip artwork horizontally (left-right mirror)

asset.flip_verticalboolean= false

Flip artwork vertically (top-bottom mirror)

asset.sizeobject

Custom size override. Both width and height are optional (min: 1 pixel each).

asset.size.widthinteger

Custom width in pixels (min: 1)

asset.size.heightinteger

Custom height in pixels (min: 1)

asset.positionobject

Custom position override in pixels.

asset.position.topinteger

Top offset in pixels

asset.position.leftinteger

Left offset in pixels

colorobject

Color overlay configuration. Either asset or color (or both) must be provided.

color.hexstringRequired

Hex color code in #RRGGBB format (e.g., '#FF5733'). Must match pattern: #[0-9A-Fa-f]{6}.

color.blending_modestring= normal

Blend mode for the color overlay. All 29 Photoshop blend modes supported. See Blend Modes section below for the full list.

adjustment_layersobject

Image adjustments applied to the user's artwork before blending into the mockup. Applied after fit transformation. Does not affect PSD-level adjustments.

Adjustment Layers

brightnessinteger= 0

Brightness adjustment (-150 to 150). 0 = no change.

contrastinteger= 0

Contrast adjustment (-100 to 100). 0 = no change.

saturationinteger= 0

Saturation adjustment (-100 to 100). 0 = no change, -100 = grayscale.

vibranceinteger= 0

Vibrance adjustment (-100 to 100). Similar to saturation but preserves skin tones.

opacityinteger= 100

Artwork opacity (0 to 100). 0 = fully transparent, 100 = fully opaque.

blurinteger= 0

Gaussian blur amount (0 to 100). 0 = sharp, 100 = max blur. Useful for background effects.

Export Options

image_formatenum= webp

Output format: webp (30-70% smaller, recommended), png (lossless, quality setting ignored), or jpg (smallest, no transparency).

image_sizeinteger= 1920

Output width in pixels (100-10000). Height is auto-calculated from the PSD aspect ratio.

qualityinteger= 95

Compression quality for JPG and WebP (1-100). Ignored for PNG, which is always lossless.

WebP Recommended

WebP format is 30-70% smaller than PNG with similar visual quality. Perfect for web and e-commerce. PNG quality setting is ignored since PNG is always lossless.

Full Request Example

1{
2  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
3  "smart_objects": [
4    {
5      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
6      "asset": {
7        "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
8        "content_type": "image/png",
9        "fit": "cover"
10      },
11      "color": {
12        "hex": "#FF5733",
13        "blending_mode": "multiply"
14      },
15      "adjustment_layers": {
16        "brightness": 10,
17        "contrast": 5
18      }
19    }
20  ],
21  "export_options": {
22    "image_format": "webp",
23    "image_size": 1920,
24    "quality": 95
25  }
26}

Code Examples

Render Mockup

bash

1curl -X POST "https://api.sudomock.com/api/v1/renders" \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: sm_your_api_key" \
4  -d '{
5    "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
6    "smart_objects": [{
7      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
8      "asset": {
9        "url": "https://your-domain.com/design.png",
10        "fit": "cover"
11      }
12    }],
13    "export_options": {
14      "image_format": "webp",
15      "image_size": 1920,
16      "quality": 95
17    }
18  }'

Response

Success Response

200OK

Response 200 OK

1{
2  "success": true,
3  "data": {
4    "print_files": [
5      {
6        "export_path": "https://cdn.sudomock.com/renders/c315f78f-.../render_1711234567890.webp",
7        "smart_object_uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9"
8      }
9    ]
10  }
11}

Response Fields

successbooleanRequired

Always true for successful renders.

dataobjectRequired

Response data wrapper containing the rendered output.

data.print_filesarrayRequired

Array of rendered output files.

data.print_files[].export_pathstringRequired

CDN URL to the rendered mockup image. For standard API users, files are stored under renders/ and subject to a 7-day retention policy. For custom domain users, files are stored under cdn-renders/ with no automatic expiry.

data.print_files[].smart_object_uuidstringRequired

UUID of the first smart object in the request. When multiple smart objects are rendered, this references the first one.

Error Responses

400Bad Request

Invalid request parameters (e.g., smart object UUID not found in the mockup, invalid mockup UUID format).

json

1{
2  "detail": "Smart object 128394ee-... not found in mockup",
3  "success": false
4}

401Unauthorized

Missing or invalid API key / Bearer token. Possible messages: "Not authenticated", "Invalid API key format. Must start with 'sm_'", "Invalid or revoked API key".

json

1{
2  "detail": "Not authenticated",
3  "success": false
4}

402Payment Required

Insufficient credits or no active subscription. The response includes actionable links and credit reset timing.

json

1{
2  "error": "credits_exhausted",
3  "message": "You've run out of credits for this billing period.",
4  "actions": [
5    { "label": "Enable Pay-As-You-Go", "url": "https://sudomock.com/dashboard/billing?action=enable-payg" },
6    { "label": "Upgrade Plan", "url": "https://sudomock.com/pricing" }
7  ],
8  "credits_reset_at": "2026-04-01T00:00:00Z"
9}

404Not Found

Mockup UUID does not exist.

json

1{
2  "detail": "Mockup not found: c315f78f-d2c7-4541-b240-a9372842de94",
3  "success": false
4}

422Validation Error

Request body fails schema validation (e.g., missing required fields, invalid types, asset and color both omitted from a smart object, empty smart_objects array).

json

1{
2  "detail": "Validation error",
3  "errors": [
4    {
5      "field": "body -> smart_objects -> 0",
6      "message": "Invalid value for field: body -> smart_objects -> 0"
7    }
8  ],
9  "success": false
10}

429Too Many Requests

Rate limit or concurrent render limit exceeded. Includes structured retry information.

json

1{
2  "detail": "Rate limit exceeded. Try again in 30 seconds.",
3  "error": {
4    "type": "rate_limit_exceeded",
5    "code": "RATE_LIMIT_EXCEEDED",
6    "limit": 1000,
7    "remaining": 0,
8    "reset_seconds": 30,
9    "retry_after": 30,
10    "resource": "api"
11  }
12}

500Internal Server Error

Rendering failed unexpectedly. Error messages are user-friendly and suggest next steps.

json

1{
2  "detail": "Rendering failed unexpectedly. Please try again or contact support. (Error: INTERNAL_ERROR)",
3  "success": false
4}

502Bad Gateway

Failed to download a user-provided image URL. The upstream image source returned an error or is unreachable.

json

1{
2  "detail": "Image not found for 'Front Design'. example.com returned HTTP 404.",
3  "success": false
4}

Try It Live

POST/api/v1/renders

Render a mockup with your design.

API Key

Get your API key from the Dashboard

Request Body

Image Fit Modes

The fit parameter controls how your design is placed within the smart object bounds:

Mode	Behavior	Use Case
`fill`	Stretches to fill entire area (may distort if aspect ratios differ)	When aspect ratio matches or distortion is acceptable
`contain`	Fits inside preserving aspect ratio (may leave empty space)	When the full design must be visible
`cover`	Fills the area and crops excess (no distortion, no empty space)	Most common for product mockups

Working with Smart Object Bounds

When rendering, it helps to understand how the smart object metadata from the upload response relates to your design:

Typical Integration Workflow

Get smart object metadata from upload

The size field tells you the design canvas dimensions (e.g., 3000x3413)

Prepare your design at the size dimensions

For best quality, create designs at the size.width x size.height resolution

Render with the smart object UUID

The API handles scaling to the position bounds automatically

Design Resolution Tip

Always design at the size dimensions from the upload response. The design will be automatically scaled to fit the position bounds on the mockup canvas. This ensures maximum quality.

Custom Position Overrides

You can override the default positioning using asset.size and asset.position:

Custom Position Override

1{
2  "smart_objects": [{
3    "uuid": "smart-object-uuid",
4    "asset": {
5      "url": "https://example.com/design.png",
6      "fit": "cover",
7      "size": { "width": 2000, "height": 2000 },
8      "position": { "top": 100, "left": 50 }
9    }
10  }]
11}

Use position overrides when you need precise control over design placement, such as centering a logo or offsetting a pattern.

Blend Modes

Apply color overlays with any of the 29 supported blending modes. All standard Photoshop blend modes are supported. Use underscore or space separators (e.g., soft_light or soft light).

Normal

normal

dissolve

pass through

Darken

darken

multiply

color burn

linear burn

darker color

Lighten

lighten

screen

color dodge

linear dodge

add

lighter color

Contrast

overlay

soft light

hard light

vivid light

linear light

pin light

hard mix

Inversion

difference

exclusion

subtract

divide

Component (HSL)

hue

saturation

color

luminosity

Bulk Rendering

Parallel Renders

For bulk rendering, send parallel requests up to your plan's parallel render limit. Each request is independent-no need to wait for previous renders to complete.

Need a feature that's not here? Request it or see what's planned.

Bulk Rendering Example

1// JavaScript: Render 10 variations in parallel
2const designs = [
3  "https://cdn.example.com/design-1.png",
4  "https://cdn.example.com/design-2.png",
5  // ... more designs
6];
7
8const renderPromises = designs.map(designUrl =>
9  fetch("https://api.sudomock.com/api/v1/renders", {
10    method: "POST",
11    headers: {
12      "Content-Type": "application/json",
13      "x-api-key": "sm_your_api_key"
14    },
15    body: JSON.stringify({
16      mockup_uuid: "your-mockup-uuid",
17      smart_objects: [{
18        uuid: "smart-object-uuid",
19        asset: { url: designUrl, fit: "cover" }
20      }]
21    })
22  }).then(r => r.json())
23);
24
25const results = await Promise.all(renderPromises);
26const renderUrls = results.map(r => r.data.print_files[0].export_path);

Upload PSD n8n Integration