POST

SudoAI Render

Render your artwork onto a SudoAI mockup. You set the mockup up once in the dashboard (photo, mask, print area), then call this endpoint with the mockup and print area UUIDs to render any design programmatically.

POST/api/v1/sudoai/2d-mockup/render

5 credits per render

Set up the mockup once, then render any design

SudoAI 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 with the Include / Exclude toggle to refine the mask, 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-mockup/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?

An earlier preview tried to do everything in one call from a raw product photo, auto-detecting the printable surface on the fly. In practice that auto-detection was unreliable, and renders often came out misaligned or failed outright. Doing the setup once, where you confirm the mask and the print area yourself, makes every subsequent render land correctly. It is a one-time step per mockup, not per render.

Request

Headers

X-API-KeystringRequired

Your SudoMock API key starting with sm_

Content-TypestringRequired

Must be application/json

Request Body

mockup_uuidstringRequired

UUID of the SudoAI 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

Mesh warp strength for fabric curvature (0 to 2). 0 disables warping. Higher values increase the warp effect following the surface shape.

edge_expandinteger= 0

Edge expansion using region growing (0 to 50). Expands artwork to fill edges better. 0 disables.

texture_strengthinteger= 0

Texture bake strength (0 to 100). Overlays the source surface texture onto the artwork for a more realistic look. 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  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
3  "print_areas": [
4    {
5      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
6      "artwork_url": "https://your-domain.com/design.png",
7      "adjustments": {
8        "brightness": 0,
9        "contrast": 0,
10        "opacity": 100,
11        "saturation": 0,
12        "vibrance": 0,
13        "blur": 0,
14        "blend_mode": "multiply",
15        "warp_strength": 1.5,
16        "edge_expand": 0,
17        "texture_strength": 0
18      },
19      "placement": {
20        "position": "center",
21        "coverage": 70,
22        "fit": "contain"
23      }
24    }
25  ],
26  "export_options": {
27    "image_format": "webp",
28    "image_size": 1920,
29    "quality": 95
30  }
31}

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 Mockup

bash

1curl -X POST "https://api.sudomock.com/api/v1/sudoai/2d-mockup/render" \
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    "print_areas": [
7      {
8        "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
9        "artwork_url": "https://your-domain.com/design.png",
10        "placement": {
11          "position": "center",
12          "coverage": 70,
13          "fit": "contain"
14        }
15      }
16    ],
17    "export_options": {
18      "image_format": "webp",
19      "image_size": 1920,
20      "quality": 95
21    }
22  }'

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        "print_area_uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
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[].print_area_uuidstring

UUID of the print area this file was rendered for

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 mockup_uuid or 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}

Legacy Path

/api/v1/sudoai/render is a deprecated alias

The older path /api/v1/sudoai/render still works and accepts the same body described here, but it is a deprecated alias kept for backward compatibility. New integrations should use /api/v1/sudoai/2d-mockup/render.

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.

POST/api/v1/sudoai/2d-mockup/render

Render artwork onto a mockup you set up in the dashboard. Use your own mockup_uuid and print_areas[].uuid.

API Key

Get your API key from the Dashboard

Request Body

SudoAI vs Standard Render API

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

	SudoAI Render	Standard Render
Template	A product photo with a mask + 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

AI-assisted surface and background selection lets SudoAI turn a single product photo into a reusable mockup, then warp any artwork 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

Refine the mask during setup

In the mask step, use the Include / Exclude toggle to add or remove regions until the printable surface is clean. A precise mask 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-mockup/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      mockup_uuid: mockupUuid,
19      print_areas: [
20        { uuid: printAreaUuid, artwork_url: url }
21      ]
22    })
23  }).then(r => r.json())
24);
25
26const results = await Promise.all(renders);

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

Render Mockup (PSD)Upload PSD