POST /api/v1/photo-mockups/{mockup_id}/render
uuid for a print area from data.quads,
or surface_uuid for a product from data.surfaces. Sending both, or sending
the mockup’s own id as a target, is rejected. Each entry also needs artwork:
artwork_url, base64, or a color. Supply a colour alongside artwork to tint
it.
A surface target
Placement
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, top_left,
top_center, top_right, center_left, center_right, bottom_left,
bottom_center, bottom_right. Offsets are measured in target pixels from that
anchor, positive right and positive down.
rotation is applied before positioning, in degrees, clockwise positive. A
rotated design occupies its rotated bounding box, so a 100 by 50 box at
"rotation": 45 lands as a 106 by 106 footprint. width and height describe
the box before the turn.
Adjustments
adjustments shapes the artwork, not the photograph: brightness (-150 to
150), contrast, saturation and vibrance (-100 to 100), opacity and
blur (0 to 100), plus blend_mode.
Pick the blend mode from the product, not from the design. multiply is the
default because it reads like ink on material: on a black tee a white logo comes
out grey. When a brand colour has to match the file you supplied, send
"blend_mode": "normal" and white stays white on any product colour. Blend mode
is per entry, so one area can hold an exact logo while another stays on
multiply. The remaining 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 (smallest at the same quality, the default), png
(lossless, quality ignored) or jpg (no transparency). image_size is the
output width in pixels, 100 to 10000, and the height follows the source aspect
ratio.
dpi writes a print resolution tag into the file metadata, 72 to 2400. 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. Files
carry a default 25.4 DPI tag when you leave it out.
More than one design at a time
A render names up to eight targets, so one call can dress the front and the sleeve of the same photograph in one image.Two targets, one image
Render a set from one mockup
"is_async": true and collect the results from jobs
instead of holding connections open.
202 Accepted
status_url, or subscribe to photo_mockup_render.succeeded and
photo_mockup_render.failed. A finished job puts the image in result_url.
What comes back
200 OK
422 almost always means a target problem: a missing print_areas, an entry
without exactly one id, an entry without artwork or colour, or a sizing option
on the wrong kind of target. The response names the field. Every status this
endpoint returns is listed in Errors.
Next
Render endpoint
The full contract, with examples in cURL, Python and JavaScript.
Print areas and surfaces
Where the target ids come from.