Smart objects

A smart object is a Photoshop layer that holds image data as a container rather than as flat pixels. In a mockup template it marks where artwork goes. Upload returns one entry per visible smart object, and that entry is how you address the area at render time.

What an entry looks like

One smart object from the upload response

{
  "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
  "name": "Front Design",
  "layer_name": "Smart Object 1",
  "size": { "width": 3000, "height": 3413 },
  "position": {
    "x": 450,
    "y": 380,
    "width": 1200,
    "height": 1400
  },
  "quad": [
    [450, 380],
    [1650, 380],
    [1650, 1780],
    [450, 1780]
  ],
  "blend_mode": "multiply",
  "required": true
}

Field	What it tells you
`uuid`	The handle you send back in a render.
`name`, `layer_name`	The layer as the designer named it. `layer_name` is the raw PSD name.
`size`	The area’s own dimensions. Author artwork at these numbers.
`position`	Where the area lands on the canvas after transforms, for previews.
`quad`	The four corner points when the area carries a perspective transform. Included on Scale plans.
`blend_mode`	The blend mode the layer was authored with.
`required`	Whether the template expects this area to be filled.

Address it in a render

Fill one area

{
  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
  "smart_objects": [
    {
      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
      "asset": {
        "url": "https://your-cdn.com/front.png",
        "fit": "crop"
      }
    }
  ]
}

A template can hold as many areas as the designer built, including smart objects nested inside other smart objects. Send one entry per area you want to change and leave the rest out; anything you omit renders as authored.

Fill two areas in one render

{
  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
  "smart_objects": [
    {
      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
      "asset": {
        "url": "https://your-cdn.com/front.png",
        "fit": "crop"
      }
    },
    {
      "uuid": "7c41a9f2-31b8-4e55-9c02-6ad3f4e91b77",
      "asset": {
        "url": "https://your-cdn.com/sleeve.png",
        "fit": "fit"
      }
    }
  ]
}

Each entry needs an asset, a color, or both. An entry that carries neither returns 422.

Match slots by name, not by order

Array order follows the layer stack, and a designer who reorders layers in Photoshop changes it. Build a lookup from the names your template is authored with.

Resolve a slot by name

def slot_uuid(mockup, layer_name):
    for smart_object in mockup["smart_objects"]:
        if smart_object["name"] == layer_name:
            return smart_object["uuid"]
    raise KeyError(f"{layer_name} is not a slot in this template")

front = slot_uuid(mockup, "Front Design")

Linked smart objects

A smart object whose content lives in an external file, such as @artwork.psb, uploads and renders from its placement geometry, so you do not need to run Embed Linked first. Embedding still gives the highest fidelity. When a linked smart object carries no usable placement geometry, the render returns a permanent 422.

422 LINKED_SMART_OBJECT_CONTENT_MISSING

{
  "success": false,
  "error_code": "LINKED_SMART_OBJECT_CONTENT_MISSING",
  "message": "A linked smart object has no usable placement geometry.",
  "detail": "Embed the smart object in Photoshop, or supply the design at render time."
}

That error does not clear on retry. Run Layer > Smart Objects > Embed Linked and upload the file again, or send the artwork in the render body.

Hidden smart objects

A smart object that is hidden in Photoshop is not exposed as a slot and is not rendered. Uploads that contain one come back flagged, so you know which layers to turn on before uploading again. Hidden text layers behave differently, and both rules are on Hidden layers.

Colour and tone on the same area

The same entry can carry a colour overlay and adjustment values alongside the artwork.

Artwork, colour and tone together

{
  "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
  "asset": {
    "url": "https://your-cdn.com/front.png",
    "fit": "crop"
  },
  "color": { "hex": "#FF5733", "blending_mode": "multiply" },
  "adjustment_layers": { "brightness": 10, "contrast": 5 }
}

Artwork placement

Fit, size, position, rotation, colour and tone in detail.

Fit and blend modes

How artwork meets an area, and how it sits on the material.

Overview

PSD mockups

Photo mockups

Text and fonts

Integrations

Reference

Advanced

Changes

What an entry looks like

Address it in a render

Match slots by name, not by order

Linked smart objects

Hidden smart objects

Colour and tone on the same area

Artwork placement

Fit and blend modes

​What an entry looks like

​Address it in a render

​Match slots by name, not by order

​Linked smart objects

​Hidden smart objects

​Colour and tone on the same area

Artwork placement

Fit and blend modes

What an entry looks like

Address it in a render

Match slots by name, not by order

Linked smart objects

Hidden smart objects

Colour and tone on the same area