POST

Render (2D)

Render your artwork onto a 2D mockup. You set the mockup up once in the dashboard (photo, printable surface, print area), then call this endpoint with the mockup UUID in the path and the print area UUIDs in the body to render any design programmatically.

POST/api/v1/sudoai/2d-mockups/{mockup_uuid}/render

5 credits per render

Set up the mockup once, then render any design

2D Mockups rendering is a two-part flow. First you set up a mockup once in the dashboard: upload a product photo, mark the printable surface, and define the print area. After that, this endpoint renders any artwork onto that saved mockup using its mockup_uuid andprint_areas[].uuid. You reuse the same setup for every render.

How It Works

Set up your mockup in the dashboard (once)

Open Dashboard → 2D Mockups and follow the 3-step editor: upload the product photo, mark the printable surface, then draw the print area. SudoMock saves it and assigns a mockup_uuid plus a uuid for each print area.

Copy the working request from the Code tab

The editor has a Code tab that generates a ready-to-run request for your mockup, with the correct mockup_uuid andprint_areas[].uuid already filled in. Pick your language and copy it.

Render any artwork programmatically

Send POST /api/v1/sudoai/2d-mockups/{mockup_uuid}/render with yourartwork_url (and optional placement / adjustments) to render. Swap the artwork on every call to render a new design onto the same saved mockup.

Why is there a setup step?

Confirming the printable surface and print area once, up front, makes every render land correctly. It is a one-time step per mockup, not per render.

Prefer no backend? Embed Studio

Rendering from your server is one path. If you would rather let your customers place their own artwork on the storefront, embed the Studio editor with one iframe. Studio handles upload, placement, live preview, and add to cart for you.

Security

Studio uses an opaque, origin-bound session token, and config writes are gated to your API key. Studio requests and responses expose no pipeline internals, only the mockup contract. See the Studio security model.

Request

Headers

X-API-KeystringRequired

Your SudoMock API key starting with sm_

Content-TypestringRequired

Must be application/json

Request Body

mockup_uuidstringRequired

Path parameter in the URL, not the body: UUID of the 2D mockup you set up in the dashboard. Find it in the editor's Code tab, or in the URL of the mockup in Dashboard > 2D Mockups.

print_areasarrayRequired

One entry per print area you want to render into. Each entry targets a saved print area by its uuid and supplies the artwork and options for it.

export_optionsobject

Output format, size, and quality settings for the rendered file.

Print Area Object

Each item in print_areas targets one saved print area and describes what to render into it.

uuidstringRequired

UUID of a print area saved on the mockup. Must match a print area created during dashboard setup. The Code tab fills this in for you.

artwork_urlstring

Publicly reachable URL of the artwork/design to place in this print area. Required unless color is provided.

colorstring

Color fill in hex format (e.g., '#FF0000'). Use alone for a solid color fill, or together with artwork_url to apply a color overlay.

adjustmentsobject

Adjustment parameters for the artwork in this print area (brightness, contrast, blend mode, warp, etc.).

placementobject

How the artwork is positioned and sized within this print area (position, coverage, fit, offset, scale, rotation).

Artwork or Color Required

Each print area must include at least one of artwork_url orcolor. You can provide both to apply a color overlay on top of your artwork.

Adjustments

brightnessinteger= 0

Brightness adjustment (-150 to 150)

contrastinteger= 0

Contrast adjustment (-100 to 100)

opacityinteger= 100

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

saturationinteger= 0

Saturation adjustment (-100 to 100)

vibranceinteger= 0

Vibrance adjustment (-100 to 100)

blurinteger= 0

Gaussian blur amount (0 to 100)

blend_modestring= multiply

Blend mode for artwork compositing. Use 'multiply' for realistic fabric texture blending, or 'normal' for no texture effect.

warp_strengthnumber= 1.5

Warp strength for fabric curvature (0 to 2). 0 disables warping. Higher values increase how strongly the artwork follows the surface shape.

edge_expandinteger= 0

Edge expansion (0 to 50). Grows the artwork outward to fill the edges better. 0 disables.

texture_strengthinteger= 0

Texture strength (0 to 100). Increases how realistically the artwork's texture matches the product surface. 0 disables.

Placement

Controls how the artwork is positioned and sized within the print area.

positionenum= center

Predefined position within the print area

coverageinteger= 70

Percentage of the print area to cover (10 to 100). Ignored when an explicit scale is provided.

fitenum= contain

How to fit the artwork: 'fill' (stretch), 'contain' (fit inside, preserve aspect ratio), 'cover' (fill and crop)

scalenumber

Explicit scale multiplier (1.0 = original size). When set, it overrides coverage. Use for precise sizing carried over from manual canvas positioning.

rotationnumber= 0

Rotation in degrees. Applied to the artwork before placement.

offset_xinteger= 0

Horizontal pixel offset from the print area center. Positive moves right, negative moves left.

offset_yinteger= 0

Vertical pixel offset from the print area center. Positive moves down, negative moves up.

Available Position Values

The position parameter accepts a 3x3 grid of predefined positions within the print area:

top_left

top_center

top_right

center_left

center

center_right

bottom_left

bottom_center

bottom_right

Export Options

image_formatenum= webp

Output format: png, jpg, or webp

image_sizeinteger= 2048

Output width in pixels (100-10000). Height scales proportionally. This sets the actual pixel dimensions of the file.

qualityinteger= 90

Compression quality for JPG/WebP (1-100). Ignored for PNG.

dpiinteger= null

Print resolution tag written into the output file metadata (72-2400). Metadata only; it does not change the pixels. image_size controls the actual pixels. For a print file, size your pixels: image_size = print_inches x dpi (e.g. 12 in x 300 = 3600 px). All formats (JPG, PNG, WebP) carry the tag; JPG and PNG are recommended for the widest print-tool compatibility. Opt-in: when omitted, files carry a default 25.4 DPI tag.

Full Request Example

1{
2  "print_areas": [
3    {
4      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
5      "artwork_url": "https://your-domain.com/design.png",
6      "adjustments": {
7        "brightness": 0,
8        "contrast": 0,
9        "opacity": 100,
10        "saturation": 0,
11        "vibrance": 0,
12        "blur": 0,
13        "blend_mode": "multiply",
14        "warp_strength": 1.5,
15        "edge_expand": 0,
16        "texture_strength": 0
17      },
18      "placement": {
19        "position": "center",
20        "coverage": 70,
21        "fit": "contain"
22      }
23    }
24  ],
25  "export_options": {
26    "image_format": "webp",
27    "image_size": 1920,
28    "quality": 95
29  }
30}

Code Examples

The Code tab in the editor generates these snippets for your own mockup, with the real mockup_uuid andprint_areas[].uuid already filled in. The examples below use placeholder UUIDs.

Render (2D)

bash

1curl -X POST "https://api.sudomock.com/api/v1/sudoai/2d-mockups/c315f78f-d2c7-4541-b240-a9372842de94/render" \
2  -H "Content-Type: application/json" \
3  -H "X-API-Key: sm_your_api_key" \
4  -d '{
5    "print_areas": [
6      {
7        "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
8        "artwork_url": "https://your-domain.com/design.png",
9        "placement": {
10          "position": "center",
11          "coverage": 70,
12          "fit": "contain"
13        }
14      }
15    ],
16    "export_options": {
17      "image_format": "webp",
18      "image_size": 1920,
19      "quality": 95
20    }
21  }'

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/sudoai/abc123.webp",
7        "duration_ms": 1840,
8        "export_format": "webp"
9      }
10    ]
11  }
12}

Response Fields

successbooleanRequired

Always true for successful responses

dataobjectRequired

Response data wrapper

data.print_filesarrayRequired

Array of rendered output files, one per rendered print area

data.print_files[].export_pathstringRequired

CDN URL to the rendered mockup image

data.print_files[].duration_msinteger

Time in milliseconds the render took to produce this file

data.print_files[].export_formatstring

Output format that was used (png, jpg, or webp)

Error Responses

404Not Found

json

1{
2  "detail": "Mockup not found",
3  "success": false
4}

Returned when mockup_uuid does not match a mockup on your account. Copy the exact value from the editor's Code tab, or from the mockup's URL in Dashboard → 2D Mockups.

422Validation Error

json

1{
2  "detail": "Validation error",
3  "errors": [
4    {"field": "print_areas", "message": "Field required"}
5  ],
6  "success": false
7}

Returned when required fields are missing or invalid. The most common cause is sending the body without print_areas, or aprint_areas[].uuid that is not a valid UUID. Each print area also needs at least one of artwork_url or color. The Code tab produces a body that already satisfies these requirements.

401Unauthorized

json

1{
2  "detail": "Invalid or missing API key",
3  "success": false
4}

402Payment Required

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}

429Too Many Requests

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

json

1{
2  "detail": "Something went wrong while processing your image. Please try again.",
3  "success": false
4}

Retired Paths

Earlier 2D render paths were retired

Two earlier paths are no longer available and now return 404: the singular/api/v1/sudoai/2d-mockup/render and its older alias/api/v1/sudoai/render. The mockup UUID moved from the request body into the URL path. Use the canonical endpoint POST /api/v1/sudoai/2d-mockups/{mockup_uuid}/render and send only print_areas and export_options in the body.

Try It Live

Replace the placeholder UUIDs below with values from your own mockup. The fastest way to get a working request is the Code tab in the editor — it fills in the correct mockup_uuid andprint_areas[].uuid for you.

2D Mockups vs Standard Render API

2D Mockups and the standard Render API serve different use cases. Here is when to use each:

	2D Mockups Render	Standard Render
Template	A product photo with a marked surface + print area	A PSD with smart object layers
Setup	Mark surface + print area in the dashboard (once)	Upload a prepared PSD (once)
Render input	mockup_uuid + print_areas[].uuid	mockup_uuid + smart_objects[].uuid
Credits	5 per render	1 per render
Best for	Quick mockups from a single product photo	Professional templates, high-volume automation
Perspective	Automatic surface warp from the product photo	Baked into PSD smart objects

A single product photo becomes a reusable mockup, then any artwork warps onto the printable surface with realistic perspective. No PSD template required.

Image Fit Modes

The placement.fit parameter controls how your artwork is placed within the print area:

Mode	Behavior	Use Case
`fill`	Stretches to fill entire area (may distort)	When aspect ratio matches the print area
`contain`	Fits inside, preserves aspect ratio, may leave space	When design must be fully visible (default)
`cover`	Fills area, preserves aspect ratio, may crop edges	All-over prints and full-surface designs

Blend Modes

The adjustments.blend_mode parameter controls how artwork blends with the product surface:

multiply

Realistic fabric texture (default)

normal

No texture, artwork as-is

Multiply for Realism

Use multiply blend mode for garments and textured surfaces. It lets the fabric texture show through, making the design look printed rather than pasted on. Use normal for hard surfaces like mugs or phone cases where texture blending is not desired.

Tips for Best Results

Mark the surface precisely

Take a moment to mark the printable surface cleanly during setup. A precise surface gives a precise render on every call.

Use transparent PNG artwork

Artwork with a transparent background composites cleanly. JPG artwork will include its white background.

Reuse one mockup for many designs

The same mockup_uuid and print_areas[].uuid work for every render. Swap only artwork_url to render a new design onto the same product.

Adjust coverage for design sizing

The default coverage: 70 works well for most logos and centered designs. Increase to 80-100 for all-over prints, or decrease to 30-40 for small chest logos.

Batch Rendering

Parallel Renders

To render many designs on the same mockup, send parallel requests that reuse the samemockup_uuid and print_areas[].uuid and vary only theartwork_url.

Batch Rendering on One Mockup

1// JavaScript: Render multiple designs on the same mockup
2const mockupUuid = "c315f78f-d2c7-4541-b240-a9372842de94";
3const printAreaUuid = "128394ee-6758-4f2f-aa36-e2b19b152bd9";
4const designs = [
5  "https://cdn.example.com/design-1.png",
6  "https://cdn.example.com/design-2.png",
7  "https://cdn.example.com/design-3.png",
8];
9
10const renders = designs.map(url =>
11  fetch(`https://api.sudomock.com/api/v1/sudoai/2d-mockups/${mockupUuid}/render`, {
12    method: "POST",
13    headers: {
14      "Content-Type": "application/json",
15      "X-API-Key": "sm_your_api_key"
16    },
17    body: JSON.stringify({
18      print_areas: [
19        { uuid: printAreaUuid, artwork_url: url }
20      ]
21    })
22  }).then(r => r.json())
23);
24
25const results = await Promise.all(renders);

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

2D Mockups (Setup)Studio