Smart Object Operations Migration

This guide helps you migrate smart object layer operations from V1's /documentCreate and /documentOperations endpoints to V2's /create-composite endpoint.

data-variant=info

data-slots=text

Overview

V1 Endpoints:

• /pie/psdService/documentCreate - Create documents with smart object layers
• /pie/psdService/documentOperations - Add/edit smart object layers

V2 Endpoint: /v2/create-composite with edits.layers

Smart Object Types

• Embedded Smart Objects - The source file is embedded in the PSD
• Linked Smart Objects - The source file is linked externally (smartObject.isLinked: true in V2)

Adding Smart Object Layers

V1 approach: documentOperations

curl -X POST \
  https://image.adobe.io/pie/psdService/documentOperations \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [{
    "href": "<SIGNED_GET_URL>",
    "storage": "external"
  }],
  "options": {
    "layers": [
      {
        "type": "smartObject",
        "name": "Logo Smart Object",
        "add": {
          "insertTop": true
        },
        "input": {
          "href": "<SMART_OBJECT_SOURCE_URL>",
          "storage": "external"
        },
        "smartObject": {
          "linked": false
        }
      }
    ]
  },
  "outputs": [{
    "href": "<SIGNED_POST_URL>",
    "storage": "external",
    "type": "image/vnd.adobe.photoshop"
  }]
}'

V2 approach

curl -X POST \
  https://photoshop-api.adobe.io/v2/create-composite \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<SIGNED_GET_URL>"
    }
  },
  "edits": {
    "layers": [
      {
        "type": "smart_object_layer",
        "name": "Logo Smart Object",
        "operation": {
          "type": "add",
          "placement": {
            "type": "top"
          }
        },
        "smartObject": {
          "smartObjectFile": {
            "source": {
              "url": "<SMART_OBJECT_SOURCE_URL>"
            }
          }
        }
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "<SIGNED_POST_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}'

Key Migration Changes

1. Layer Type Name

V1: "type": "smartObject"

V2: "type": "smart_object_layer"

2. Source Reference

V1: Uses input property

{
  "type": "smartObject",
  "input": {
    "href": "<URL>",
    "storage": "external"
  }
}

V2: Uses smartObject.smartObjectFile.source property

{
  "type": "smart_object_layer",
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<URL>"
      }
    }
  }
}

data-variant=warning

data-slots=text

3. Linked vs Embedded

V1: Explicit smartObject.linked property

{
  "type": "smartObject",
  "smartObject": {
    "linked": false
  }
}

V2: Use smartObject.isLinked (true for linked, false for embedded)

{
  "type": "smart_object_layer",
  "smartObject": {
    "isLinked": true,
    "smartObjectFile": {
      "source": {
        "url": "<URL>"
      }
    }
  }
}

data-variant=info

data-slots=text

4. Add Operation Structure

V1: Separate add block

{
  "type": "smartObject",
  "add": {
    "insertTop": true
  }
}

V2: Unified operation block with smartObject property

{
  "type": "smart_object_layer",
  "operation": {
    "type": "add",
    "placement": {
      "type": "top"
    }
  },
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<SMART_OBJECT_SOURCE_URL>"
      }
    }
  }
}

Supported Source File Types

Smart objects can contain various file types:

V1 Supported:

• PSD (image/vnd.adobe.photoshop)
• JPEG (image/jpeg)
• PNG (image/png)
• AI / Adobe Illustrator (application/illustrator)
• PDF (application/pdf)

V2 Supported:

• PSD (image/vnd.adobe.photoshop)
• JPEG (image/jpeg)
• PNG (image/png)
• TIFF (image/tiff)
• SVG (image/svg+xml)
• AI / Adobe Illustrator (application/illustrator)
• PDF (application/pdf)

data-variant=info

data-slots=text

Transform Mode

V2 introduces transformMode property that controls how the smart object is transformed:

• "none" - No transform applied (use original size)
• "custom" - Use explicit transform values (offset, dimension, angle, etc.)
• "fit" - Fit the smart object to maintain aspect ratio
• "fill" - Fill the available space

{
  "type": "smart_object_layer",
  "transformMode": "fit",
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<SMART_OBJECT_URL>"
      }
    }
  }
}

Smart Object with Transformations

V1 approach

{
  "type": "smartObject",
  "name": "Scaled Logo",
  "add": {
    "insertTop": true
  },
  "input": {
    "href": "<URL>",
    "storage": "external"
  },
  "bounds": {
    "left": 100,
    "top": 100,
    "width": 500,
    "height": 300
  }
}

V2 approach

{
  "type": "smart_object_layer",
  "name": "Scaled Logo",
  "operation": {
    "type": "add",
    "placement": {
      "type": "top"
    }
  },
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<URL>"
      }
    }
  },
  "transformMode": "custom",
  "transform": {
    "offset": {
      "horizontal": 100,
      "vertical": 100
    },
    "dimension": {
      "width": 500,
      "height": 300
    }
  }
}

data-variant=info

data-slots=text

Editing Existing Smart Objects

V1 approach

{
  "options": {
    "layers": [
      {
        "name": "Existing Smart Object",
        "edit": {},
        "visible": false
      }
    ]
  }
}

V2 approach

{
  "edits": {
    "layers": [
      {
        "type": "smart_object_layer",
        "name": "Existing Smart Object",
        "operation": {
          "type": "edit"
        },
        "isVisible": false
      }
    ]
  }
}

data-variant=info

data-slots=text

Replacing Smart Object Content

V1 approach

{
  "options": {
    "layers": [
      {
        "name": "Existing Smart Object",
        "edit": {},
        "input": {
          "href": "<NEW_SOURCE_URL>",
          "storage": "external"
        }
      }
    ]
  }
}

V2 approach

{
  "edits": {
    "layers": [
      {
        "type": "smart_object_layer",
        "name": "Existing Smart Object",
        "operation": {
          "type": "edit"
        },
        "smartObject": {
          "smartObjectFile": {
            "source": {
              "url": "<NEW_SOURCE_URL>"
            }
          }
        }
      }
    ]
  }
}

data-variant=info

data-slots=text

data-variant=warning

data-slots=text

Placement Options

Smart objects support the same placement options as other layers:

V1 Placement

{
  "add": {
    "insertTop": true              // or
    "insertBottom": true            // or
    "insertAbove": {"name": "..."}  // or
    "insertBelow": {"id": 123}      // or
    "insertInto": {"name": "Group"}
  }
}

V2 Placement

{
  "operation": {
    "type": "add",
    "placement": {
      "type": "top"
    }
  }
}

For relative placement use "above", "below", or "into" with referenceLayer: {"name": "..."} or {"id": 123}.

See Image Layer Operations for detailed placement patterns.

Creating Documents with Smart Objects

V1 approach: documentCreate

{
  "options": {
    "document": {
      "width": 1000,
      "height": 1000,
      "resolution": 72,
      "fill": "white",
      "mode": "rgb"
    },
    "layers": [
      {
        "type": "smartObject",
        "name": "Logo",
        "input": {
          "href": "<LOGO_URL>",
          "storage": "external"
        }
      }
    ]
  }
}

V2 approach

{
  "document": {
    "width": 1000,
    "height": 1000,
    "resolution": {"unit": "density_unit", "value": 72},
    "fill": {
      "solidColor": {
        "red": 255,
        "green": 255,
        "blue": 255
      }
    },
    "mode": "rgb"
  },
  "edits": {
    "layers": [
      {
        "type": "smart_object_layer",
        "name": "Logo",
        "operation": {
          "type": "add",
          "placement": {
            "type": "top"
          }
        },
        "smartObject": {
          "smartObjectFile": {
            "source": {
              "url": "<LOGO_URL>"
            }
          }
        }
      }
    ]
  }
}

Layer Properties

Smart objects support standard layer properties:

{
  "type": "smart_object_layer",
  "name": "My Smart Object",
  "isVisible": true,
  "protection": ["none"],
  "blendOptions": {
    "opacity": 90,
    "blendMode": "normal"
  },
  "transformMode": "custom",
  "transform": {
    "offset": {
      "horizontal": 100,
      "vertical": 100
    },
    "dimension": {
      "width": 500,
      "height": 300
    },
    "angle": 0,
    "skew": {
      "horizontal": 0,
      "vertical": 0
    },
    "anchor": {
      "horizontal": 0.5,
      "vertical": 0.5
    }
  },
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<SMART_OBJECT_URL>"
      }
    }
  }
}

data-variant=warning

data-slots=text

See Advanced Layer Operations for blend modes and transforms.

Migration Checklist

When migrating smart object operations from V1 to V2:

• Change type: "smartObject" to type: "smart_object_layer"
• Change input to smartObject.smartObjectFile.source for smart object file reference
• Change href/storage to url (storageType is not needed)
• Replace add block with operation.type: "add" and include placement
• Convert placement directives (insertTop → placement.type: "top", etc.)
• Use referenceLayer with name or id instead of relativeTo
• Add operation.type: "edit" for editing existing layers
• Convert visible to isVisible
• Lock: Change locked to protection array (see Advanced Layer Operations)
• Move opacity and blendMode under blendOptions object
• Replace bounds with transform containing offset and dimension
• Add transformMode property ("custom", "fit", "fill", or "none")
• Convert smartObject.linked to smartObject.isLinked (true for linked, false for embedded)
• Verify supported source file types in V2

Common Migration Issues

Issue: Linked smart objects

Problem: V1 used smartObject.linked, which is not the same field name in V2

Solution: Use V2 smartObject.isLinked with the same boolean intent

Issue: Source file type support

Problem: Not all file types may be supported

Solution: Verify supported types in V2 documentation before migration

Issue: Missing operation block

Problem: V2 requires explicit operation for new layers

Solution: Always include operation block when adding

{
  "type": "smart_object_layer",
  "operation": {
    "type": "add",
    "placement": {
      "type": "top"
    }
  },
  "smartObject": {
    "smartObjectFile": {
      "source": {
        "url": "<SMART_OBJECT_URL>"
      }
    }
  }
}

Complete Migration Example

V1 documentOperations:

{
  "inputs": [
    {
      "href": "<SIGNED_GET_URL>",
      "storage": "external"
    }
  ],
  "options": {
    "layers": [
      {
        "type": "smartObject",
        "name": "Logo",
        "add": {
          "insertTop": true
        },
        "input": {
          "href": "<LOGO_PSD_URL>",
          "storage": "external"
        },
        "bounds": {
          "left": 50,
          "top": 50,
          "width": 400,
          "height": 400
        },
        "smartObject": {
          "linked": false
        }
      },
      {
        "type": "smartObject",
        "name": "Product Image",
        "add": {
          "insertAbove": {
            "name": "Logo"
          }
        },
        "input": {
          "href": "<PRODUCT_IMAGE_URL>",
          "storage": "external"
        },
        "blendOptions": {
          "opacity": 85
        }
      }
    ]
  },
  "outputs": [
    {
      "href": "<SIGNED_POST_URL>",
      "storage": "external",
      "type": "image/vnd.adobe.photoshop"
    }
  ]
}

V2 create-composite:

{
  "image": {
    "source": {
      "url": "<SIGNED_GET_URL>"
    }
  },
  "edits": {
    "layers": [
      {
        "type": "smart_object_layer",
        "name": "Logo",
        "operation": {
          "type": "add",
          "placement": {
            "type": "top"
          }
        },
        "smartObject": {
          "isLinked": false,
          "smartObjectFile": {
            "source": {
              "url": "<LOGO_PSD_URL>"
            }
          }
        },
        "transformMode": "custom",
        "transform": {
          "offset": {
            "horizontal": 50,
            "vertical": 50
          },
          "dimension": {
            "width": 400,
            "height": 400
          }
        }
      },
      {
        "type": "smart_object_layer",
        "name": "Product Image",
        "operation": {
          "type": "add",
          "placement": {
            "type": "above",
            "referenceLayer": {
              "name": "Logo"
            }
          }
        },
        "smartObject": {
          "isLinked": true,
          "smartObjectFile": {
            "source": {
              "url": "<PRODUCT_IMAGE_URL>"
            }
          }
        },
        "blendOptions": {
          "opacity": 85
        }
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "<SIGNED_POST_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}

New features in V2

V2 introduces several smart object capabilities that were not available in V1:

Replacement of linked smart object with another linked smart object

V2 allows you to replace an existing linked smart object with a different linked smart object. This was not possible in V1.

Example:

{
  "edits": {
    "layers": [
      {
        "name": "Existing Linked Smart Object",
        "type": "smart_object_layer",
        "operation": {
          "type": "edit"
        },
        "smartObject": {
          "isLinked": true,
          "smartObjectFile": {
            "source": {
              "url": "<NEW_LINKED_FILE_URL>"
            }
          }
        }
      }
    ]
  }
}

Replacement of embedded smart object with linked smart object

V2 enables you to convert an embedded smart object into a linked smart object by replacing it with a linked file. This workflow was not supported in V1.

Example:

{
  "edits": {
    "layers": [
      {
        "name": "Existing Embedded Smart Object",
        "type": "smart_object_layer",
        "operation": {
          "type": "edit"
        },
        "smartObject": {
          "isLinked": true,
          "smartObjectFile": {
            "source": {
              "url": "<LINKED_FILE_URL>"
            }
          }
        }
      }
    ]
  }
}

data-variant=info

data-slots=text

Resize with linked smart objects

V1 rejected any resize (width/maxWidth) on documents containing linked smart objects. V2 removes this restriction.

Example — Width resize only:

When no edits are provided, linked file content is not available to the engine. All linked smart object layers are rasterized into pixel layers during resize.

{
  "image": {
    "source": {
      "url": "<SIGNED_INPUT_PSD_GET_URL>"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "<SIGNED_OUTPUT_POST_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop",
      "width": 200
    }
  ]
}

Result: The output PSD is resized to 200px width (aspect ratio maintained). All linked smart object layers in the document are converted to regular pixel (image) layers.

Example — Edit linked SO + width resize:

When you edit or add a linked smart object in the same request as a resize, the edited/added layer stays intact as a linked smart object (its content was provided via the API). Other linked SO layers in the document that were not edited are rasterized.

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

Result: The output PSD is resized to 200px width. The edited layer remains a linked smart object (its content was provided via the edit). All other linked SO layers in the document are rasterized into pixel layers.

Feature Availability

Currently available in V2

• ✅ Add embedded smart object layers
• ✅ Edit existing smart objects
• ✅ Replace smart object content
• ✅ Smart object transformations (transform with offset, dimension, angle, skew, anchor)
• ✅ Transform modes (custom, fit, fill)
• ✅ Layer visibility (isVisible)
• ✅ Layer locking (protection array)
• ✅ Blend options (opacity, blendMode)
• ✅ Placement options (top, bottom, above, below, into)
• ✅ Reference layer by name or ID
• ✅ Multiple source file types (PSD, JPEG, PNG, TIFF, SVG, AI, PDF)
• ✅ Linked and embedded smart objects (smartObject.isLinked)
• ✅ Resize (width/maxWidth) documents containing linked smart objects

Coming soon

Check V2 API documentation and release notes for upcoming features.

Next steps

• Review Layer Operations Overview for general concepts
• Check Image Layers for placement patterns
• See Advanced Operations for transforms and effects