Smart Object Workflow

For authentication, API key, and storage setup, see Photoshop API v1 guides overview.

Example 1: Adding a linked smart object

Add a linked smart object layer, then call generate-manifest to confirm it appears as linked in the manifest.

Placeholders for step 1

Replace these placeholders in the request payload below:

Step 1 — Create composite (add linked smart object)

Endpoint: POST /v2/create-composite

Request payload:

{
    "image": {
        "source": {
            "url": "<SIGNED_INPUT_ASSET_GET_URL>"
        }
    },
    "edits": {
        "layers": [
            {
                "type": "smart_object_layer",
                "name": "Linked Added Smart Object",
                "operation": {
                    "type": "add",
                    "placement": {
                        "type": "top"
                    }
                },
                "smartObject": {
                    "isLinked": true,
                    "smartObjectFile": {
                        "source": {
                            "url": "<SIGNED_SMART_OBJECT_ASSET_GET_URL>"
                        }
                    }
                }
            }
        ]
    },
    "outputs": [
        {
            "destination": {
                "url": "<SIGNED_OUTPUT_POST_URL>"
            },
            "mediaType": "image/vnd.adobe.photoshop"
        }
    ]
}

The generated output is a PSD with a linked smart object layer added on top, as shown in the image below.

Before: Original PSD. After: PSD with linked smart object layer on top.

Step 2 — Generate manifest

Use the presigned GET URL of the output PSD from Step 1 as image.source.url below. That URL points to the PSD you just created.

Placeholders for step 2

Replace these placeholders in the request payload below:

Endpoint: POST /v2/generate-manifest

Request payload:

{
    "image": {
        "source": {
            "url": "<SIGNED_OUTPUT_PSD_GET_URL>"
        }
    },
    "outputs": [
        {
            "destination": {
                "embedded": "json"
            },
            "mediaType": "application/json"
        }
    ]
}

Use the generated PSD's URL from Step 1 as image.source.url. A call to this API initiates an asynchronous job and returns a response containing a URL. Use the value in the href field to poll for the status of the job and the same response will also contain the JSON manifest.

Step 3 — Result: linked smart object in manifest

Relevant layer snippet from the manifest JSON:

"smartObject": {
    "isSmartObject": true,
    "isLinked": true,
    "isValid": true,
    "smartObjectData": {
        "type": "smartObject",
        "transform": [
            0,
            0,
            1000,
            0,
            1000,
            1000,
            0,
            1000
        ],
        "fileInfo": {
            "relative": "../../df06670e-467a-4880-a697-cfc162f313c3/downloads/c89b3884-3df6-444e-9540-a0c26af33ddc.png",
            "name": "c89b3884-3df6-444e-9540-a0c26af33ddc.png",
            "path": "/tmp/df06670e-467a-4880-a697-cfc162f313c3/downloads/c89b3884-3df6-444e-9540-a0c26af33ddc.png",
            "fileType": "png",
            "linked": true
        }
    }
}

As seen from the manifest snippet above — for linked smart objects, the linked property is true along with the path information to the linked file.

Example 2: Replacing a smart object with a linked file

Edit an existing smart object layer and replace its content with a different linked file. The input PSD must already contain the smart object layer you want to replace. In this example, we use the output PSD from Example 1 and replace its linked smart object with another one.

Placeholders for example 2

Replace these placeholders in the request payload below:

Step 1 — Create composite (replace with a linked smart object)

Endpoint: POST /v2/create-composite

Request payload:

{
    "image": {
        "source": {
            "url": "<SIGNED_INPUT_ASSET_GET_URL>"
        }
    },
    "edits": {
        "layers": [
            {
                "type": "smart_object_layer",
                "name": "<EXISTING_SMART_OBJECT_LAYER_NAME>",
                "operation": {
                    "type": "edit"
                },
                "smartObject": {
                    "isLinked": true,
                    "smartObjectFile": {
                        "source": {
                            "url": "<SIGNED_NEW_SMART_OBJECT_GET_URL>"
                        }
                    }
                }
            }
        ]
    },
    "outputs": [
        {
            "destination": {
                "url": "<SIGNED_OUTPUT_POST_URL>"
            },
            "mediaType": "image/vnd.adobe.photoshop"
        }
    ]
}

The generated output is a PSD with the replaced linked smart object, as shown in the image below.

Before: PSD with linked smart object (from Example 1). After: PSD with replaced linked smart object.

Opening the output PSD in Photoshop

When you open the output PSD locally in Photoshop, you may see a "missing file" prompt for the linked smart object. This is expected behavior, not a bug. The path stored inside the PSD points to the server location where the file resided during processing — that path will not resolve on your local machine. Photoshop is correctly flagging the broken link.

You have two options depending on your workflow:

1. Relink locally. Keep a copy of the source asset (the file you passed as the linked smart object) somewhere accessible on your machine. In Photoshop, use the Layer panel → Smart Objects → Relink to File,

   

   or respond to the missing-link dialog when the PSD opens. Once relinked, Photoshop will remember the new path.

   

2. Use embedded smart objects instead. If portability matters more than the linked-asset workflow — for example, when handing off the PSD to an end user who just wants to open and work without managing external files — embedded smart objects travel with the PSD and eliminate the relinking step. Set "isLinked": false (or omit isLinked) in the smartObject block to embed rather than link. Linked smart objects are the right choice when you manage your own asset pipeline and want explicit control over source files; embedded is generally smoother for hand-off scenarios.