Mockups

A mockup puts your design on a product photo: a t-shirt, a hoodie, a mug, a poster on a wall, a phone in a hand, a tote bag. The print follows the product's folds, catches its light and shadows, and stops at its edges. The design is a variable, so one mockup template renders every design you feed it.

What a mockup is

A mockup is two layers in an ordinary template:

• The product photo: an image layer. Nothing is baked into it.
• A warp layer over it, with mockup settings. Its child layers are the design. The warp bends the design onto the printable area, and the mockup settings print it through three maps made from the photo:
  • Print mask: where ink may land (white = printable). The design stops at seams, collars, handles and screen bezels.
  • Wrinkles: a displacement map derived from the photo's depth, so the print shifts with the folds instead of floating on top.
  • Look: how the photo's shading reaches the ink (shadows, highlights, grain, colour cast), how soft the print is, and how the light falls across it.
• Product color (optional): the product itself re-tinted inside the print mask, so one white tee photo becomes a navy, red or brand-coloured tee.

Because it is a normal template, everything else works the same way: variables, brand tokens, variations, bulk rendering and the Render API.

Surfaces

Pick the surface that matches the product. Each one sets a look preset and decides whether wrinkles are on by default.

The look preset is a starting point. The Look section shows five sliders: Shadow, Highlight, Texture, Match color and Glass. Each one moves a few of the detailed settings together. Advanced opens every setting (the editor remembers whether you left it open). A dot next to Reset to surface preset shows that the look no longer matches the preset, and the button brings the preset back.

Build one in the editor

1. Open the Mockups panel in the left rail. Starters are ready-made mockups from the gallery. One click drops a starter onto the canvas with its mask and wrinkles already made, fits the print box to the print area and selects the design layer. Drop your image on the print, or use Add your design. Yours lists the mockups saved as components in this space.
2. Click New and pick the photo: upload one, generate one from a prompt, or use the image layer you have selected. The editor groups the photo with a new warp layer and selects the warp.
3. Print mask: describe the printable part ("the t-shirt", "the mug body", "the phone screen") or click on the photo (shift-click excludes an area). You can also upload a mask, or Paint it with a brush and lasso. Smooth, grow, shrink or feather it until the edge sits where the print should stop.
4. Placement: the warp is placed for the surface, on the chest of a garment or across a screen or a poster face. Drag the corners and the curve handles on the canvas to fine-tune. In Warp surface you can switch between a grid, corners and a curved patch, or apply a dome, bulge or cylinder. On a mug, can or bottle, Fit to cylinder reads the print mask and bows the print's top and bottom to the rims and squeezes it toward the sides as the surface turns away; it is greyed out, with the reason on hover, when the mask does not look like a cylinder seen from the front.
5. Wrinkles: Estimate depth reads the photo's shape, and the Strength and Smoothing sliders decide how far the folds push the print. The same depth also gives the print the photo's light (see Print technique and light), and on fabric the editor takes a patch of the photo's own cloth as the print's texture.
6. Look: start with the five sliders (Shadow, Highlight, Texture, Match color, Glass) and Match photo. Glass keeps the glass's own reflections, flares and glare over the print: on a screen, or on a poster photographed behind a shop window or a glazed frame, the print should never look cleaner than the glass around it. It starts at 0.35 on screens and 0 elsewhere; 0.3–0.45 suits most glass. The first time you raise it on a mockup that has never measured its glass, the editor reads the darkest glass under the print, and everything brighter than that in the photo counts as reflection. With a shiny technique (foil, puff, embroidery, screen print) a fifth slider, Shine, sets how much the ink catches the light. Under Advanced you can adjust shadows, highlights, grain, colour cast, shading radius and gain, ink flatten, curve shade and the mask's feather, edge and erode one by one. Then:
   • Print blur softens the print to the photo's own sharpness, in photo pixels (0–2). A crisp design on a soft or upscaled photo is the first thing that gives a mockup away. Match photo measures how sharp and how grainy the photo is under the print and sets the print blur and grain for you. It runs by itself when you finish a new mockup or pick a different photo, and it costs nothing.
   • Ambient carries the photo's broad lighting into the print, so the side of the garment that faces the light is brighter and the side turned away is darker (0–1). Fold shading alone only follows small wrinkles.
   • Ink soak lets the ink sink into the material: a little less saturated, and dimmer on darker cloth (0–1). Pure, glowing ink is a common giveaway.
   • Weave lays a fine knit texture over the print that follows the folds (0–1). It shows up close and in large renders, and helps when the photo is too soft to show its own fabric texture.
   • Light from and Falloff darken the print across a flat face, away from the light. Set the direction the light comes from (in degrees, clockwise from the top: 270 is from the left) and how dark the far edge gets (0–1). Use it on billboards, signs, boxes and posters, where the photo's own shading is too even to show. It is off (0) by default.
7. Product color (optional): click + on the section, then pick a swatch. Your brand's colours come first. The product is re-tinted inside the print mask and keeps the photo's folds and light. Strength sets how much of the new colour replaces the photo's own (0–1). Keep photo brightness changes only the hue and keeps the photo's own brightness: a white tee then stays light. Leave it off to take the colour's own tone, so a white tee can become navy. To change the colour per render, type an expression such as {{ color }} or {{ brand.colors.primary }} in the colour field. Original color removes the tint.
8. Put your design inside the warp layer, and make it a variable (an image variable bound to the design layer's source). Every render then prints whatever image you pass.
9. Placement (in the inspector of the print layer or of the design inside it): place the design inside the print area. See Place the design.

The Mockup section of the inspector shows which image layer is the product photo and which surface is in use. Re-place from mask places the warp again after you change the mask.

Remove existing print erases a logo, slogan or print that is already on the product, so it cannot show through your design. It edits the photo with AI and saves the result as a new image in your media library; the mask and wrinkles stay as they are, because the framing does not change. Restore original puts the photo from before back, and Undo works too. The button is off while the photo is bound to a variable: unbind it first.

Each AI step shows its price before it runs, and you can skip it and upload or paint the map instead.

Scenes and relight

The Scene tab of the Mockups panel gives the selected mockup's photo new light or a new setting. Select the photo or its print first. The Scene row in the inspector's Mockup section opens the same tab.

• Relight presets change only the light: Studio soft, Spotlight, Sunlit blinds, Window light, Golden hour and Overcast. The product and the framing stay where they were, so the print mask and placement are kept. The AI can still move the folds a little, so the editor estimates the depth of the new photo again and the wrinkles follow it. Match photo then runs again, so the print takes on the new photo's sharpness and grain, and the light direction is read again from the new photo so the print's light falloff follows the new light (when the photo's light is unclear, the falloff is left as it was). Tick Keep current wrinkles to skip the depth step and save its credit.
• New setting presets (marked with a picture icon) move the product into a new scene: Concrete wall, Café, Marble counter, Linen table and Street. The photo's geometry changes, so the editor sets the old mask and wrinkles aside and opens Find print area with your last mask prompt filled in. If the photo has several print areas, find each one again.

Add a short note in your own words ("warmer, light from the right") to steer a preset, or use the note on its own to relight the photo. The note is screened like any other image prompt; a declined note is not run or charged (PROMPT_REJECTED, see Errors). Regenerate runs the same settings again for a new take. Try another runs the next preset in the same group. Each run shows its price first: a relight costs the edit plus one depth estimate, a new setting costs the edit (Find print area and wrinkles are charged as usual after).

Every result is saved as a new image in your media library. The last four sit under the controls: click one to use it again. Presets always start from the photo the results came from, so the edits do not stack. Original (or Restore original in the inspector) puts the photo you started with back, together with its mask, wrinkles and placement.

Place the design

The print area is the part of the photo your design prints on. While the print layer or a layer inside it is selected, the canvas shows the print area as a dashed outline.

• Snapping: drag the design and it snaps to the print area's edges, centre lines and thirds, with the usual pink guides. Dragging a corner of the print on the photo snaps to the saved print area the same way. Hold ⌥ Option while resizing to resize from the centre, and ⇧ Shift to keep the proportions.
• Print width: type how wide the print area prints, in inches or centimetres. Units then switches X, Y, W and H between pixels, inches and centimetres.
• DPI: with a print width set, an image design shows the DPI it prints at (its pixels per printed inch). Under 150 DPI it turns amber (it may print soft), and under 100 DPI it turns red.
• Contain, Cover, Stretch and Center fit the design to the print area: the whole design inside it, the area filled, the area filled exactly (stretched), or centred at its current size.
• Rotate 90° left or right, and Flip horizontal or vertical.
• Fit box to print area pins the print to the saved print area again. Save as print area saves the corners where you dragged them as the new print area.

Several print areas on one photo

A photo can carry more than one print: front and back, a sleeve, a pocket, a label. Each print area is its own print layer on the same photo, with its own mask, placement and design, and they share the photo, its wrinkles and its look.

1. Select a print (or its photo). The Mockups panel lists the photo's print areas.
2. Type or pick a name (Back, Sleeve, Pocket, Label, or your own) and click Duplicate for area. The print is copied onto the same photo and the Find print area step opens for the new area. Describe the part, for example "the left sleeve".
3. Apply this design to all areas copies the selected print's design image into every other area. Each area keeps its own placement.

The Area field in the Placement section renames an area.

All-over pattern

All-over pattern repeats the design across the whole print, so the folds, mask and shading apply to every repeat. Click + on the section, then pick Grid, Brick (every other row shifted) or Half drop (every other column shifted).

• Scale: the size of one repeat, as a multiple of the design layer (0.05–4).
• Spacing: the gap between repeats, as a fraction of a repeat (0–2).
• Offset: how far every other row or column shifts (0–1, 0.5 is half a repeat).
• Rotation: turns the whole pattern (-180° to 180°).

The first layer in the print repeats. For an all-over print, make the print area cover the whole product. Turn off prints the design once again.

Print technique and light

Print sets how the design is printed. Each technique sets its own look, and Plain puts the surface's look back:

• Screen print: flat, opaque ink with crisp edges and a hint of colour misregistration at the edges.
• DTG (direct to garment): the ink soaks into the cloth, a little duller, and the weave shows through.
• Embroidery: thread lines, a raised edge, and the design stitched in a few flat thread colours picked from the design itself. Threads sets how many (2–8, default 6): fewer gives a flatter, more stitched look. Stitch angle turns the stitch direction.
• Puff: raised ink that bulges and catches the light.
• Foil: metallic ink that mirrors the photo's light and shines where it faces the light.

Light (needs Estimate depth, or a technique): the print is relit by the photo's own folds under the key light.

• Elevation: how high the light sits above the surface, from 0 (grazing) to 90 (straight on). The direction is Light from under the Look's Advanced.
• Relight: how much the folds facing toward or away from the light brighten or darken the print (0–1).
• Edge: ink thickness, a thin shadow just outside the print's edge on the side away from the light and a highlight on the lit edge (0–1). It shows around shapes inside the print layer, so leave some transparent margin around the artwork.
• Match photo also reads the light's direction and elevation from the photo once the depth is estimated.
• Enhance photo detail upscales the photo with AI so the cloth holds up when you zoom in or render large. Pick 2x or 4x above the button, or leave both off for auto (4× for photos up to 1024 px, 2× for larger ones). On flat cotton, 2× is the safer pick: 4× can invent cloth bands the photo does not have. It runs once per photo; the mask and wrinkles stay, and Restore original puts the old photo back.
• Use photo cloth (fabric) takes a patch of bare cloth from the photo, away from the print, and uses it as the print's texture instead of the drawn knit. It blurs exactly like the photo when you zoom in.

In front: mark what sits in front of the print, such as a hand, a strap, a cord, hair or a sleeve, and the print passes behind it while the photo shows through. Pick one or more chips and click Find, or Paint it by hand with the mask tools. Remove cords under Print mask finds drawstrings and straps over the print and marks them as in front. Once something is marked, Tighten (0–6 photo pixels, blend.occluderErode) pulls its edge in when a grey halo shows beside a cord, and Soften (0–4 photo pixels, blend.occluderSoft, default 1) matches the photo's own edge softness.

Credits

The AI steps cost credits. The rendering itself is billed like any other render.

These are the default prices. A platform admin can change them, so the editor and the API always report what was charged. A step that fails is not charged.

Re-print a design on every render

Bind the design to a variable once, then pass a new value per render:

curl -X POST https://bannx.com/api/v1/templates/TEMPLATE_ID/render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "variables": { "design": "https://example.com/artwork.png" } }'

Bind the product colour the same way: set mockup.recolor.color to "{{ color }}", add a color variable, and pass "variables": { "design": "…", "color": "#b91c1c" }. One photo then renders every colourway.

Nothing about the mockup is computed again at render time. The mask, wrinkles and look are stored with the template, so a mockup render costs the same as any other still. See Rendering for formats, sizes and bulk jobs.

Build one from an agent (MCP)

Two calls build a mockup template: mockup_prepare makes the maps, and template_apply_ops adds the layers. See the MCP guide for setup.

1. Prepare the photo. Upload the product photo with media_upload (or use a fileId already in your library), then:

{ "fileId": "PHOTO_FILE_ID", "surface": "fabric", "maskPrompt": "the t-shirt" }

It returns baseUrl, baseWidth, baseHeight, the print corners (0–1 of the photo), warpNode (x, y, w, h and the warp patch), mockup (surface, mask and wrinkle maps, look) and creditsCharged. The look in mockup.blend also takes printBlur (0–2 photo pixels), ambient, inkSoak and weave (each 0–1) and lightFalloff ({ "angle": 270, "strength": 0.3 }) if you want to set them. mockup.recolor is there when you passed recolor, and you can add, change or remove it later like any other mockup setting. Segmentation and depth cost 1 credit each by default. If any step fails, nothing is charged.

With scene, baseUrl and baseFileId are the new photo, which is also saved in your media library. mockup.originalBaseSrc holds the photo you passed, so Restore original in the editor can bring it back, and scene in the response says which preset ran and whether the geometry was kept.

mockup.printArea is the print area on the photo: x, y, w and h from 0 to 1 of the photo and rotation in degrees. Add widthIn (the printed width in inches) to get print units and the DPI readout in the editor, and dpiHint for your print shop's target DPI. When you passed areas, the response has an areas list: each entry has its own label, corners, warpNode and mockup (with mockup.area set to the label). Add one more warp layer per entry, with the same baseId and its own design child.

With wrinkles, the response also has normalSrc (the photo's surface normals) and light (angle, elevation, falloff), the key light read from the photo and already set in mockup.blend.lightFalloff. On fabric it has weaveSrc, the photo's own cloth texture. Both are already in mockup. blend.relight, blend.spec (shine) and blend.edgeShadow (ink thickness) are 0–1 and blend.lightFalloff.elevation is 0–90 degrees. With occluderPrompt you get occluderSrc (also in mockup), and with enhance the new baseUrl plus originalBaseUrl. For screen, and with behindGlass, mockup.glassBlack is the glass's own black level under the print (0–1); blend.reflect (0–1, Glass in the editor) lays everything in the photo brighter than that back over the design. reflect has no effect without glassBlack. With printEffect: "embroidery", mockup.stitchAngle turns the stitches (degrees, default 45) and mockup.printPalette sets how many thread colours the design is stitched in (2–8, default 6): each region of the design takes the nearest of those colours, picked from the design itself.

For an all-over print, add mockup.pattern: { "mode": "grid", "scale": 0.25, "spacing": 0.1, "offset": 0.5, "rotation": 0 }. mode is grid, brick, half-drop or off. The warp's first child is the repeat, so size it to one motif.

2. Add the layers in one batch. Use the values from step 1. $base refers to the photo layer added earlier in the same batch:

{
  "templateId": "TEMPLATE_ID",
  "operations": [
    { "op": "setVariables", "variables": [{ "name": "design", "type": "image", "label": "Design", "default": "https://example.com/artwork.png" }] },
    { "op": "addNode", "type": "image", "ref": "base", "props": { "name": "Photo", "src": "BASE_URL", "x": 0, "y": 0, "w": 1024, "h": 1024 } },
    { "op": "addNode", "type": "warp", "ref": "print",
      "props": { "name": "Print", "...": "warpNode from step 1", "mockup": { "...": "mockup from step 1", "baseId": "$base" } },
      "children": [{ "type": "image", "props": { "src": "{{ design }}", "x": 0, "y": 0, "w": 400, "h": 360 } }] }
  ]
}

Spread warpNode into the warp's props and add baseId to mockup. The design children sit in the warp's own box: 0,0 is its top-left and warpNode.w × warpNode.h is its size. Size the template's artboard to the photo.

3. Render with template_render { "variables": { "design": "…" } }, or the Render API.

Tips for product photos

The print borrows its folds, texture and light from the photo, so the photo has to carry them:

• Use directional light (from the left or upper left) and visible folds or texture. A flat, evenly lit garment gives the print nothing to sit in, and it will look pasted on.
• Use a blank product with no logo or print where yours will go, or use Remove existing print to erase it.
• For screens, a screen that is off and black works best. On a screen that is on, keep the Screen slider low so the old picture does not show through.
• Glass (screens, shop windows, bus shelters) should show its reflections: the street, lamps, a window. Glass keeps exactly what the photo reflects, so perfectly black, reflection-free glass gives the print nothing to sit under.
• When you generate a photo in the editor, the prompt scaffold asks for all of this for you.

Related docs

• Templates: the document model, warp layers and variables
• Variables: image variables and bindings
• Rendering: formats, credits and bulk jobs
• MCP Server: mockup_prepare and template_apply_ops