Print areas and surfaces

A photo mockup carries two kinds of render target, and every render names exactly one of them per artwork.

A print area is a bounded zone drawn on a product, a chest panel or a poster face. It is four corner points, and it is addressed by print_area_id.
A surface is a whole printable product in the photograph. It is addressed by surface_uuid, and it is how you print across the entire item.

Drawing a print area on a product does not take its surface away. The same t-shirt can hold a logo zone and still accept an all over print, which is why a mockup usually returns both lists.

GET /api/v1/photo-mockups/{mockup_id}

{
  "data": {
    "mockup_id": "9b0a74cd-0ebb-4748-a748-976fec8cc000",
    "status": "ready",
    "source_width": 2000,
    "source_height": 2400,
    "quads": [
      {
        "print_area_id": "223e4567-e89b-12d3-a456-426614174001",
        "name": "Front",
        "points": [
          [420, 560], [1580, 560], [1600, 1840], [400, 1840]
        ],
        "sort_order": 0
      }
    ],
    "surfaces": [
      {
        "surface_uuid": "323e4567-e89b-12d3-a456-426614174002",
        "points": [
          [300, 380], [1700, 380], [1700, 2100], [300, 2100]
        ],
        "bbox": {
          "x": 300,
          "y": 380,
          "width": 1400,
          "height": 1720
        }
      }
    ]
  },
  "success": true
}

The coordinate space

Every point on a mockup is in source photo pixels, the space described by source_width and source_height. A print area is exactly four [x, y] points, ordered top left, top right, bottom right, bottom left, and the shape they describe has to be convex and sit inside the photograph. sort_order starts at zero and follows the photograph rather than your array: areas are ordered by their leftmost point, then top to bottom, so index zero is the leftmost area on the image. Read the order off the response instead of assuming it.

Supply your own areas at create time

If you already know where artwork belongs, send the areas with the create call. SudoMock uses them exactly and skips detection, which keeps a bulk import deterministic.

POST /api/v1/photo-mockups

{
  "source_url": "https://example.com/classic-tee-front.jpg",
  "name": "Classic tee, front",
  "print_areas": [
    {
      "name": "Front",
      "points": [
        [420, 560], [1580, 560], [1600, 1840], [400, 1840]
      ]
    }
  ]
}

Replace the areas later

The areas prepared at creation are ready to render as they are. Reach for this endpoint only when you want your own placement. It replaces the whole list in the order you send, so include every area you mean to keep. PUT print areas

const response = await fetch("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas", {
  method: "PUT",
  headers: {
    "x-api-key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "print_areas": [
      {
        "points": [
          [
            420,
            560
          ],
          [
            1580,
            560
          ],
          [
            1600,
            1840
          ],
          [
            400,
            1840
          ]
        ]
      },
      {
        "points": [
          [
            700,
            300
          ],
          [
            1300,
            300
          ],
          [
            1300,
            520
          ],
          [
            700,
            520
          ]
        ]
      }
    ]
  }),
});

const data = await response.json();
console.log(data);

<?php

$payload = <<<'JSON'
{
  "print_areas": [
    {
      "points": [
        [
          420,
          560
        ],
        [
          1580,
          560
        ],
        [
          1600,
          1840
        ],
        [
          400,
          1840
        ]
      ]
    },
    {
      "points": [
        [
          700,
          300
        ],
        [
          1300,
          300
        ],
        [
          1300,
          520
        ],
        [
          700,
          520
        ]
      ]
    }
  ]
}
JSON;

$ch = curl_init("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: sm_your_api_key",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

payload = {
    "print_areas": [
        {
            "points": [
                [
                    420,
                    560
                ],
                [
                    1580,
                    560
                ],
                [
                    1600,
                    1840
                ],
                [
                    400,
                    1840
                ]
            ]
        },
        {
            "points": [
                [
                    700,
                    300
                ],
                [
                    1300,
                    300
                ],
                [
                    1300,
                    520
                ],
                [
                    700,
                    520
                ]
            ]
        }
    ]
}

response = requests.put(
    "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas",
    headers={"x-api-key": "sm_your_api_key"},
    json=payload,
)

response.raise_for_status()
print(response.json())

require "net/http"
require "uri"

uri = URI("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas")
request = Net::HTTP::Put.new(uri)
request["x-api-key"] = "sm_your_api_key"
request["Content-Type"] = "application/json"

request.body = <<~JSON
  {
    "print_areas": [
      {
        "points": [
          [
            420,
            560
          ],
          [
            1580,
            560
          ],
          [
            1600,
            1840
          ],
          [
            400,
            1840
          ]
        ]
      },
      {
        "points": [
          [
            700,
            300
          ],
          [
            1300,
            300
          ],
          [
            1300,
            520
          ],
          [
            700,
            520
          ]
        ]
      }
    ]
  }
JSON

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "print_areas": [
    {
      "points": [
        [
          420,
          560
        ],
        [
          1580,
          560
        ],
        [
          1600,
          1840
        ],
        [
          400,
          1840
        ]
      ]
    },
    {
      "points": [
        [
          700,
          300
        ],
        [
          1300,
          300
        ],
        [
          1300,
          520
        ],
        [
          700,
          520
        ]
      ]
    }
  ]
}`)

	req, err := http.NewRequest("PUT", "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("x-api-key", "sm_your_api_key")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
{
  "print_areas": [
    {
      "points": [
        [
          420,
          560
        ],
        [
          1580,
          560
        ],
        [
          1600,
          1840
        ],
        [
          400,
          1840
        ]
      ]
    },
    {
      "points": [
        [
          700,
          300
        ],
        [
          1300,
          300
        ],
        [
          1300,
          520
        ],
        [
          700,
          520
        ]
      ]
    }
  ]
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas"))
    .header("x-api-key", "sm_your_api_key")
    .header("Content-Type", "application/json")
    .PUT(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

using System.Net.Http;
using System.Text;

var payload = """
{
  "print_areas": [
    {
      "points": [
        [
          420,
          560
        ],
        [
          1580,
          560
        ],
        [
          1600,
          1840
        ],
        [
          400,
          1840
        ]
      ]
    },
    {
      "points": [
        [
          700,
          300
        ],
        [
          1300,
          300
        ],
        [
          1300,
          520
        ],
        [
          700,
          520
        ]
      ]
    }
  ]
}
""";

var request = new HttpRequestMessage(HttpMethod.Put, "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas");
request.Headers.Add("x-api-key", "sm_your_api_key");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var client = new HttpClient();
var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

curl -X PUT "https://api.sudomock.com/api/v1/photo-mockups/9b0a74cd-0ebb-4748-a748-976fec8cc000/print-areas" \
  -H "x-api-key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "print_areas": [
      {
        "points": [
          [
            420,
            560
          ],
          [
            1580,
            560
          ],
          [
            1600,
            1840
          ],
          [
            400,
            1840
          ]
        ]
      },
      {
        "points": [
          [
            700,
            300
          ],
          [
            1300,
            300
          ],
          [
            1300,
            520
          ],
          [
            700,
            520
          ]
        ]
      }
    ]
  }'

The response returns the saved areas with the ids you render against.

200 OK

{
  "data": {
    "mockup_id": "9b0a74cd-0ebb-4748-a748-976fec8cc000",
    "print_areas": [
      {
        "print_area_id": "223e4567-e89b-12d3-a456-426614174001",
        "points": [
          [420, 560], [1580, 560], [1600, 1840], [400, 1840]
        ],
        "sort_order": 0
      },
      {
        "print_area_id": "223e4567-e89b-12d3-a456-426614174002",
        "points": [
          [700, 300], [1300, 300], [1300, 520], [700, 520]
        ],
        "sort_order": 1
      }
    ]
  },
  "success": true
}

Sending an empty array removes every bounded zone. The product surface stays, so the mockup still renders as a whole item.

Clear the zones

{ "print_areas": [] }

Limits worth knowing

A mockup currently holds at most eight print areas, and a single render names at most eight targets. Split a product that needs more into a second mockup of the same photograph. Print areas can only be written once the mockup reports status: "ready". A write sent earlier returns 409 with MOCKUP_NOT_SETTABLE; wait for the create job to finish and send it again. See Errors.

Points are validated against the source image, not against the product. A convex quad that falls outside source_width or source_height is rejected with 400 rather than clamped, so you find the mistake at setup instead of in a render.

Reviewing placement by eye

Numbers are the fast path, and a photograph sometimes needs a look. The mockup editor at Dashboard, Photo mockups opens the prepared result, lets you drag the corners, and saves the same areas this endpoint writes. Its Code tab prints a ready to run request carrying the real mockup_id and target id.

Print areas on a PSD template

A PSD mockup marks placement differently: a smart object can carry print_area_presets, named boxes returned with the upload response that you apply instead of measuring bounds yourself.

From the PSD upload response

{
  "smart_objects": [
    {
      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
      "print_area_presets": [
        {
          "uuid": "preset-full",
          "name": "Full coverage",
          "size": { "width": 3000, "height": 3413 },
          "position": {
            "x": 0,
            "y": 0,
            "width": 3000,
            "height": 3413
          }
        },
        {
          "uuid": "preset-center",
          "name": "Centre logo",
          "size": { "width": 1000, "height": 1000 },
          "position": {
            "x": 1000,
            "y": 1200,
            "width": 1000,
            "height": 1000
          }
        }
      ]
    }
  ]
}

A preset is a marker on the artboard, not a division of it. It tells you where a design is meant to sit; it does not cut the smart object into pieces.

Render artwork

Place a design on a target and get a finished image.

Print areas endpoint

The write contract, with examples.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Changes

Print areas and surfaces

The coordinate space

Supply your own areas at create time

Replace the areas later

Limits worth knowing

Reviewing placement by eye

Print areas on a PSD template

Next

Render artwork

Print areas endpoint

​The coordinate space

​Supply your own areas at create time

​Replace the areas later

​Limits worth knowing

​Reviewing placement by eye

​Print areas on a PSD template

​Next

Render artwork

Print areas endpoint

The coordinate space

Supply your own areas at create time

Replace the areas later

Limits worth knowing

Reviewing placement by eye

Print areas on a PSD template

Next