A mockup renders once it reports
status: "ready". The body is shown field
by field, with examples in eight languages, on the
render endpoint.Choose a target
Each entry names exactly one target:uuid, which takes the print_area_id
of a saved print area, or surface_uuid, which takes the id of a whole
product or of a room’s main wall. Sending both, or sending the mockup’s own
id as a target, is rejected. Both ids come from
Print areas and surfaces.
Each entry also needs artwork: artwork_url, base64, or a color, either
a hex code or a colour saved on the mockup. Supply a colour alongside artwork
to tint it.
Rendering a catalogue is the other direction: same mockup, same target, one
call per design, fired in parallel. For a large set add "is_async": true and
collect each result from
its job instead of holding
connections open. The job envelope and the events it fires are in
Photo mockups.
Placement
Placement fields sit in each entry’splacement object.
position, offset_x, offset_y and rotation work on either kind of
target. Sizing follows the target you picked.
An option sent to the wrong kind of target returns
422 rather than a guess,
and so does half a box. The exact box is also how you leave padding inside an
area: ask for less than the area and anchor it where you want it.
position anchors the artwork on a three by three grid, center by default.
Offsets are measured in target pixels from that anchor, positive right and
positive down. rotation turns the artwork before it is positioned, and a
rotated design occupies its rotated bounding box, so width and height
describe the box before the turn.
With tile set to true, the sizing answer is one tile and position with
the offsets sets where the grid starts. The pattern fills every part of the
target, including the parts something in front of it splits apart. A tile
needs a sizing answer; without one the request returns 422. Send the artwork
to Check seams before you tile it, so a
line where the copies meet shows up in the answer rather than on the product.
Check and fix pattern seams covers the check and the
repair.
tile_spacing leaves a gap between the tiles. It is a percentage of the tile
size, from 0 to 100. The horizontal gap is that percent of the tile width, and
the vertical gap is that percent of the tile height. It is used only when
tile is true. Leave it out, or send 0, and the tiles touch. The gap is
transparent, so the product shows through between the tiles.
422.
Adjustments
adjustments shapes the artwork, not the photograph: brightness,
contrast, saturation, vibrance, opacity, blur and blend_mode.
Pick the blend mode from the product, not from the design. multiply is the
default because it reads like ink on material, and it is per entry, so one
area can carry a printed look while another matches a brand colour exactly.
The seven modes and what each is for are in
Fit and blend modes.
Two flags sit beside the adjustments. flip_horizontal and flip_vertical
mirror the artwork before placement. remove_background isolates the subject
onto a transparent cutout first, which is charged per artwork on top of the
render, so pass artwork that is already transparent when you have it.
Export options
image_format takes webp, the default and the smallest at the same quality,
png for lossless output, or jpg where transparency is not needed. For images
you upload to a marketplace such as Etsy, use jpg: some marketplace upload
pipelines read WebP colours with reduced contrast, and a JPG arrives as rendered.
image_size is the length of the output’s longer side in pixels, and the other
side follows the photograph’s proportions.
dpi writes a print resolution tag into the file metadata. It tags the file
and does not change the pixels, so size a print file with
image_size = print_inches x dpi: twelve inches at 300 is 3600 pixels. Leave
it out and the file carries a default 25.4 DPI tag, whatever the mockup
photograph was tagged with, so send dpi on anything headed for print, and
pick png or jpg there for the widest print tool support.
A finished render answers with data.print_files, one entry per image,
carrying the export_path to fetch. A 422 almost always means a target or
placement problem: no print_areas, an entry without exactly one id, an entry
without artwork, a sizing option on the wrong target, a tile without a sizing
answer, or a tile_spacing outside 0 to 100. The response names the field,
and every status this endpoint returns is listed in Errors.
Learn more
Print areas and surfaces
See where the target ids come from.
Fit and blend modes
Compare every fit and blend mode on one page.
Next steps
Render endpoint
Send the call and read the body field by field.
Photo mockups
Run a render in the background and watch its events.