Render artwork onto a photo mockup

The mockup id travels in the path. The body carries only what changes between renders: one entry per target, and how you want the file exported. A single call dresses up to eight targets, so the front and the sleeve of one photograph land in the same image.

​

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. 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’s placement 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.

​

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 output width in pixels, and the height follows the source aspect ratio. 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 problem: no print_areas, an entry without exactly one id, an entry without artwork, or a sizing option on the wrong target. The response names the field, and every status this endpoint returns is listed in Errors.

​

Learn more

​

Next steps